From a2b3d7ae17a3eaecc85aba0e56210cb3f8678ab9 Mon Sep 17 00:00:00 2001 From: Nils-Magnus Date: Tue, 14 Jan 2020 18:14:36 +0100 Subject: [PATCH 01/42] fixes docstring formatting in RDS and removes the README.md from the top page --- doc/source/index.rst | 2 - doc/source/user/index.rst | 3 +- doc/source/user/proxies/rds_v3.rst | 34 +++++++++++----- .../user/resources/rds/v3/configuration.rst | 2 +- otcextensions/sdk/rds/v3/_proxy.py | 33 ++++++++------- otcextensions/sdk/rds/v3/instance.py | 40 +++++++++---------- 6 files changed, 63 insertions(+), 51 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index c113cd71d..30eac0d11 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -47,8 +47,6 @@ For Contributors contributor/index -.. include:: ../../README.rst - General Information ------------------- diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 3d9c2d0fe..6c6b477ae 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -127,7 +127,8 @@ control which services can be used. Key Management Service Object Block Storage Volume Backup Service - RDS + Relational Database Service RDS V1 + Relational Database Service RDS V3 Resource Interface ~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/user/proxies/rds_v3.rst b/doc/source/user/proxies/rds_v3.rst index 2efeddecc..c5240b482 100644 --- a/doc/source/user/proxies/rds_v3.rst +++ b/doc/source/user/proxies/rds_v3.rst @@ -18,16 +18,14 @@ Datastore Operations .. autoclass:: otcextensions.sdk.rds.v3._proxy.Proxy - .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.datastore_versions - .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.get_datastore_version .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.datastore_types + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.datastores Flavor Operations ^^^^^^^^^^^^^^^^^ .. autoclass:: otcextensions.sdk.rds.v3._proxy.Proxy - .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.get_flavor .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.flavors Instance Operations @@ -36,20 +34,36 @@ Instance Operations .. autoclass:: otcextensions.sdk.rds.v3._proxy.Proxy .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.create_instance - .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.update_instance .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.delete_instance .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.get_instance .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.find_instance .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.instances - + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.restore_instance + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.get_instance_restore_time Backup Operations ^^^^^^^^^^^^^^^^^ .. autoclass:: otcextensions.sdk.rds.v3._proxy.Proxy - .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.backups - .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.create_backup - .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.delete_backup - .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.get_backup_policy - .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.set_backup_policy + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.backups + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.create_backup + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.delete_backup + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.find_backup + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.backup_download_links + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.get_instance_backup_policy + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.set_instance_backup_policy + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.wait_for_backup + +Configuration Operations +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: otcextensions.sdk.rds.v3._proxy.Proxy + + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.configurations + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.get_configuration + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.find_configuration + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.create_configuration + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.delete_configuration + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.update_configuration + .. automethod:: otcextensions.sdk.rds.v3._proxy.Proxy.apply_configuration diff --git a/doc/source/user/resources/rds/v3/configuration.rst b/doc/source/user/resources/rds/v3/configuration.rst index 2952778eb..a6b436702 100644 --- a/doc/source/user/resources/rds/v3/configuration.rst +++ b/doc/source/user/resources/rds/v3/configuration.rst @@ -9,5 +9,5 @@ The Configuration Class The ``Configuration`` class inherits from :class:`~otcextensions.sdk.sdk_resource.Resource`. -.. autoclass:: otcextensions.sdk.rds.v3.configuration.ConfigurationGroup +.. autoclass:: otcextensions.sdk.rds.v3.configuration.Configuration :members: diff --git a/otcextensions/sdk/rds/v3/_proxy.py b/otcextensions/sdk/rds/v3/_proxy.py index 6ed09c8ee..ee8eed0c4 100644 --- a/otcextensions/sdk/rds/v3/_proxy.py +++ b/otcextensions/sdk/rds/v3/_proxy.py @@ -248,7 +248,7 @@ def get_configuration(self, cg): or a object of :class:`~otcextensions.sdk.rds.v3.configuration.Configuration`. - :returns: A Configuration Object + :returns: A Configuration object :rtype: :class:`~otcextensions.rds.v3.configuration.Configuration` """ return self._get(_configuration.Configuration, cg) @@ -258,13 +258,12 @@ def find_configuration(self, name_or_id, ignore_missing=True): :param name_or_id: The name or ID of configuration. :param bool ignore_missing: When set to ``False`` - :class:`~openstack.exceptions.ResourceNotFound` will be - raised when the resource does not exist. - When set to ``True``, None will be returned when - attempting to find a nonexistent resource. - :returns: One - :class:`~otcextensions.sdk.rds.v3.configuration.Configuration` - or None + :class:`~openstack.exceptions.ResourceNotFound` will be + raised when the resource does not exist. + When set to ``True``, None will be returned when + attempting to find a nonexistent resource. + :returns: A configuration object + :rtype: :class:`~otcextensions.sdk.rds.v3.configuration.Configuration` """ return self._find(_configuration.Configuration, name_or_id, @@ -273,7 +272,7 @@ def find_configuration(self, name_or_id, ignore_missing=True): def create_configuration(self, **attrs): """Create DB Configuration. - :param dict **attrs: Dict to overwrite Configuration object + :param dict \*\*attrs: Dict to overwrite Configuration object :returns: A Configuration Object :rtype: :class:`~otcextensions.sdk.rds.v3.configuration.Configuration` @@ -359,7 +358,7 @@ def delete_backup(self, backup, ignore_missing=True): """Deletes given backup :param instance: The value can be either the ID of an instance or a - :class:`~openstack.database.v3.instance.Instance` instance. + :class:`~otcextension.sdk.rds.v3.instance.Instance` instance. :param bool ignore_missing: When set to ``False`` :class:`~openstack.exceptions.ResourceNotFound` will be raised when the instance does not exist. @@ -377,14 +376,14 @@ def find_backup(self, name_or_id, instance, ignore_missing=True): :param name_or_id: The name or ID of a instance. :param instance: The value can be either the ID of an instance or a - :class:`~openstack.database.v3.instance.Instance` instance. - :param bool ignore_missing: When set to ``False`` - :class:`~openstack.exceptions.ResourceNotFound` will be - raised when the resource does not exist. - When set to ``True``, None will be returned when - attempting to find a nonexistent resource. + :class:`~otcextension.sdk.rds.v3.instance.Instance` instance. + :param bool ignore_missing: When set to ``False`` + :class:`~openstack.exceptions.ResourceNotFound` will be + raised when the resource does not exist. + When set to ``True``, None will be returned when + attempting to find a nonexistent resource. :returns: One :class:`~otcextensions.sdk.rds.v3.backup.Backup` - or None + or None """ instance = self._get_resource(_instance.Instance, instance) return self._find(_backup.Backup, diff --git a/otcextensions/sdk/rds/v3/instance.py b/otcextensions/sdk/rds/v3/instance.py index e1820b399..75e95e24f 100644 --- a/otcextensions/sdk/rds/v3/instance.py +++ b/otcextensions/sdk/rds/v3/instance.py @@ -69,7 +69,7 @@ class Instance(_base.Resource): #: *Type:str* maintenance_window = resource.Body('maintenance_window') #: Node information - #: Indicates the primary/standby DB instance information. + #: Indicates the primary/standby DB instance information. #: *Type:list* nodes = resource.Body('nodes', type=list) #: Password of the default user. @@ -174,25 +174,25 @@ def find(cls, session, name_or_id, ignore_missing=True, **params): """Find a resource by its name or id. :param session: The session to use for making this request. - :type session: :class:`~keystoneauth1.adapter.Adapter` + :type session: :class:`~keystoneauth1.adapter.Adapter` :param name_or_id: This resource's identifier, if needed by - the request. The default is ``None``. + the request. The default is ``None``. :param bool ignore_missing: When set to ``False`` - :class:`~openstack.exceptions.ResourceNotFound` will be - raised when the resource does not exist. - When set to ``True``, None will be returned when - attempting to find a nonexistent resource. + :class:`~openstack.exceptions.ResourceNotFound` will be + raised when the resource does not exist. + When set to ``True``, None will be returned when + attempting to find a nonexistent resource. :param dict params: Any additional parameters to be passed into - underlying methods, such as to - :meth:`~openstack.resource.Resource.existing` - in order to pass on URI parameters. + underlying methods, such as to + :meth:`~openstack.resource.Resource.existing` + in order to pass on URI parameters. :return: The :class:`Resource` object matching the given name or id - or None if nothing matches. + or None if nothing matches. :raises: :class:`openstack.exceptions.DuplicateResource` if more - than one resource is found for this request. + than one resource is found for this request. :raises: :class:`openstack.exceptions.ResourceNotFound` if nothing - is found and ignore_missing is ``False``. + is found and ignore_missing is ``False``. """ session = cls._get_session(session) @@ -222,20 +222,20 @@ def fetch(self, session, requires_id=True, """Get a remote resource based on this instance. :param session: The session to use for making this request. - :type session: :class:`~keystoneauth1.adapter.Adapter` + :type session: :class:`~keystoneauth1.adapter.Adapter` :param boolean requires_id: A boolean indicating whether resource ID - should be part of the requested URI. + should be part of the requested URI. :param str base_path: Base part of the URI for fetching resources, if - different from - :data:`~openstack.resource.Resource.base_path`. + different from :data:`~openstack.resource.Resource.base_path`. :param str error_message: An Error message to be returned if - requested object does not exist. + requested object does not exist. :param dict params: Additional parameters that can be consumed. + :return: This :class:`Resource` instance. :raises: :exc:`~openstack.exceptions.MethodNotSupported` if - :data:`Resource.allow_fetch` is not set to ``True``. + :data:`Resource.allow_fetch` is not set to ``True``. :raises: :exc:`~openstack.exceptions.ResourceNotFound` if - the resource was not found. + the resource was not found. """ data = self.list(session, paginated=False, id=self.id) result = self._get_one_match(self.id, data) From 3f2ff7bbbcd907f251509bd51c16f9063c05c6e9 Mon Sep 17 00:00:00 2001 From: Nils-Magnus Date: Wed, 15 Jan 2020 14:24:58 +0100 Subject: [PATCH 02/42] adds more structure to the documentation and provides a history --- doc/source/demo.rst-delme | 1 + doc/source/glossary.rst | 11 +++++ doc/source/history.rst | 75 +++++++++++++++++++++++++++++ doc/source/index.rst | 99 ++++++++++++++++++++------------------- doc/source/save | 89 +++++++++++++++++++++++++++++++++++ doc/source/user/index.rst | 14 ++++++ 6 files changed, 242 insertions(+), 47 deletions(-) create mode 100644 doc/source/demo.rst-delme create mode 100644 doc/source/history.rst create mode 100644 doc/source/save diff --git a/doc/source/demo.rst-delme b/doc/source/demo.rst-delme new file mode 100644 index 000000000..0f09d35b6 --- /dev/null +++ b/doc/source/demo.rst-delme @@ -0,0 +1 @@ +Ich bin hier diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst index 3bdbde41d..ddae083ab 100644 --- a/doc/source/glossary.rst +++ b/doc/source/glossary.rst @@ -102,3 +102,14 @@ Glossary volume OpenStack Volume (Cinder). Also the attribute name of the virtual disks managed by the OpenStack Volume service. + + +Naming conventions +------------------ + +OTC Extensions <- präferierte Schreibweise des Projekts +OTCE <- informelle Abkürzung, nicht in der offiziellen Dokumentation verwenden +otcextensions <- Name des Python-Package +python-otcextensions <- GitHub-Projektname +golang-otcextensions <- potenzielle anderes Projekt (= golang-gophercloud) +haskell-otcextensions diff --git a/doc/source/history.rst b/doc/source/history.rst new file mode 100644 index 000000000..ba30948c1 --- /dev/null +++ b/doc/source/history.rst @@ -0,0 +1,75 @@ +History of the OTC Extensions +============================= + +This project may seem complicated as it has some dependencies and +obscure naming conventions. Sometimes understanding the OTC +Extensions's heritage helps to mitigate those pains. + +OpenStack itself started as a set of services, and developers very +early decided that having a (more or less) decoupled set of services +would be the best choice for such a huge, distributed +system. Distributed services need to talk to each other. That's why +each service provides an interface. As OpenStack uses RESTful +webservices as a communication fabric, this interface is called and +API. Most of the (quantitive) implementation effort of OpenStack is to +implement the services behind those API endpoints. + +However, there are also clients using and consuming those +services. Thus they need to talk to the APIs. Once a service was +implemented its developers tried to use the service. While using +generic HTTP tools like curl or wget might be a workaround for first +tests, dealing with authentication schemes, token handling, encoding, +encapsulation, and header and body handling made it not really +convenient to work with them. + +Now specific tools emerged implementing the client side of a +service. There have been novatools for the compute service, +glancetools for the image service, neutrontool for the network, and +many more. + +Once developers discovered that they needed to re-implement a lot of +duplicating code for each new service again, they started to factor +out common code pieces. That actually took place in several places +simulteanously: The **shade** library abstracted handling of +resources, that different services implemented with a similar +way. Many resource, for example, implement the so-called CRUD +operations for creating, reading, updating, and deleting them. + +A second major field for client application was authentication and +autorization against the cloud. While in the beginning environment +variables appeared to come in handy, having all runtime configuration +options in a single file simplified the overall management of your +cloud setup. This idea was introduced by **os-client-config**. It +centralized the environment variable handling, but even more +important, it introduced the **clouds.yaml** configuration file. + +In a major refactoring session, in 201X the developers combined both +libraries into a single one called **OpenStack SDK**. That in turn +would become the building block of one unified CLI tool that is +capable of adressing all OpenStack services from a single +command. This is the OpenStack Client. It has several subcommands that +work in a similar manner and share a common syntax. + +In a perfect world now all would have been fine. In reality, however, +not all clouds are the same. Some offer additional, vendor specific +services (or, which is worse) implement a subset of services +differently. To reflect these circumstances, 2018, Artem Goncharov +implemented a plugin mechanism into both OpenStack SDK and into the +OpenStack client. This way the SDK and CLI can be extended and +maintained without touching the generic code. One instance making use +of this plugin mechanism are the OTC Extensions, this very project. + +Wann gab es die ersten Clients für OpenStack? + +Wer hat wann erstmals die Notwendigkeit gesehen, etwas zu +vereinheitlichen? Wann? Haben wir da irgendwo einen Link drauf? + +Wer hat Shade begonnen und wann? + +Wer hat os-client-config beginnen und wann? + +Wann/warum wurden die Projekte aufgegeben? + +Wer maintaint was? + +https://docs.openstack.org/openstacksdk/latest/contributor/history.html diff --git a/doc/source/index.rst b/doc/source/index.rst index 30eac0d11..569b58957 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,59 +1,64 @@ Welcome to the OTC Extensions of the OpenStack SDK and CLI! =========================================================== -**Note:** Currently documentation is a mostly a copy of OpenStackSDK -documentation (used version). -It will be soon extended with OTC services. Keep watching - -This documentation is split into three sections: - -* an :doc:`installation ` guide -* a section for :doc:`users ` looking to build applications - which make use of OpenStack -* a section for those looking to :doc:`contribute ` - to this project - -Installation ------------- - -.. toctree:: - :maxdepth: 2 - - install/index - -CLI Usage ---------- - -This guides give you an overview of the CLI commands - -.. toctree:: - :maxdepth: 2 - - cli/index - -For Users ---------- - .. toctree:: - :maxdepth: 2 - - user/index - -For Contributors ----------------- + :includehidden: + :maxdepth: 1 -.. toctree:: - :maxdepth: 2 + Installation + CLI Usage + Package Reference + Contributing + History + Glossary of Terms + Release Notes - contributor/index +Accessing the `OpenStack API`_ directly can be tedious. The `OpenStack +SDK`_ is a Python based client library that simplifies building +applications to work with OpenStack clouds. This project, OTC +Extensions, augments this SDK and adds extra functionality offered by +the `Open Telekom Cloud`_. The OTC Extensions serve two purposes: +Firstly, they provide Python classes and methods to attach your own +code to the cloud. For example, `Ansible modules`_ use this +way. Secondly, the OTC Extensions automatically extend the `OpenStack +Client`_, the CLI tool to manage the OpenStack cloud. + +This documentation is split into four sections, adressing several use +cases: + +* The :doc:`installation ` guide explains system + administrators and developers how to setup the project from + operation system packages, from pip, directly from sources and other + installation forms. Configuration + +* Users who want to access Open Telekom Cloud specific services with + :doc:`command line tools ` find documentation of all of + their opetions and properties in this section. + +* Developers, who plan to write own Python code, may access the API + more easily by using the OTC Extensions' classes and methods. The + :doc:`architecture and interfaces ` are documented in + this section. + +* Developers, who want to :doc:`contribute ` to the + project find helpful background information. General Information ------------------- -General information about the SDK including a glossary and release history. +In a `glossary`_ important terms and their naming conventions are described. -.. toctree:: - :maxdepth: 1 +There is a `history`_ explaing the ancestry of this project. This may +or may not be insightful if you want to understand the projects +architecture. - Glossary of Terms - Release Notes +There is a `release history`_ available. + +.. _OpenStack SDK: https://docs.openstack.org/openstacksdk/ +.. _OpenStack API: https://openstack.org/api-ref/ +.. _Open Telekom Cloud: https://open-telekom-cloud.com/ +.. _Ansible modules: https://github.com/OpenTelekomCloud/ansible-collections/ +.. _OpenStack Client: https://docs.openstack.org/python-openstackclient/ +.. _glossary: +.. _history: +.. _release history: diff --git a/doc/source/save b/doc/source/save new file mode 100644 index 000000000..579299a6d --- /dev/null +++ b/doc/source/save @@ -0,0 +1,89 @@ +Welcome to the OTC Extensions of the OpenStack SDK and CLI! +=========================================================== + +OTC Extensions <- präferierte Schreibweise des Projekts +OTCE <- informelle Abkürzung, nicht in der offiziellen Dokumentation verwenden +otcextensions <- Name des Python-Package +python-otcextensions <- GitHub-Projektname +golang-otcextensions <- potenzielle anderes Projekt (= golang-gophercloud) +haskell-otcextensions + +Accessing the `OpenStack API`_ can be tedious. The `OpenStack SDK`_ is +a Python based programming library that simplifies using that API. +This project, OTC Extensions, augments this SDK and adds extra +functionality offered by the `Open Telekom Cloud`_. The OTC Extensions +serve two purposes: Firstly, they provide Python classes and methods +to attach your own code to the cloud. For example, `Ansible modules`_ +use this way. Secondly, the OTC Extensions automatically extend the +`OpenStack Client`_, the CLI tool to manage the OpenStack cloud. + +This documentation is split into four sections, adressing several use +cases: + +* The :doc:`installation ` guide explains system + administrators and developers how to setup the project from + operation system packages, from pip, directly from sources and other + installation forms. **** Configuration **** + +* Users who want to access Open Telekom Cloud specific services with + :doc:`command line tools ` find documentation of all of + their opetions and properties in this section. + +* Developers, who plan to write own Python code, may access the API + more easily by using the OTC Extensions' classes and methods. The + :doc:`architecture and interfaces ` are documented in + this section. + +* Developers, who want to :doc:`contribute ` to the + project find helpful background information. + + +Installation +------------ + +.. toctree:: + :maxdepth: 2 + + install/index + +CLI Usage +--------- + +This guides give you an overview of the CLI commands + +.. toctree:: + :maxdepth: 2 + + cli/index + +For Users +--------- + +.. toctree:: + :maxdepth: 2 + + user/index + +For Contributors +---------------- + +.. toctree:: + :maxdepth: 2 + + contributor/index + +General Information +------------------- + +General information about the SDK including a glossary and release history. + +.. toctree:: + :maxdepth: 1 + + Glossary of Terms + Release Notes + Ressources + +# Links references by the text above: + +.. _OpenStack SDK: https://docs.openstack.org/openstacksdk/latest/ diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 6c6b477ae..ea53594d7 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,6 +1,20 @@ Getting started with the OTCExtensions SDK ========================================== +The SDK/OTCE contain an abstraction interface layer. Clouds can do many +things, but there are probably only about 10 of them that most people +care about with any regularity. + +If you want to do complicated things, the per-service oriented +portions of the SDK are for you. + +However, if what you want is to be able to write an application that +talks to clouds no matter what crazy choices the deployer has made in +an attempt to be more hipster than their self-entitled narcissist +peers, then the Cloud Abstraction layer is for you. + + + Please note that OTCExtensions provides an extension to the OpenStackSDK. Please refer to it's documentation for the details From f6d7b1932df5297157f158f1b72912637dbdf3ac Mon Sep 17 00:00:00 2001 From: Nils-Magnus Date: Thu, 16 Jan 2020 02:18:18 +0100 Subject: [PATCH 03/42] cleans up the documentation. adds a page about coverage of services. purges a few temporary files. moves the issues into the doctree and links them. adds a section naming conventions to the glossary. fixes here and there the spelling of projects and other names. --- doc/source/coverage.rst | 47 ++++++++++++++++++++++++++++ open_points => doc/source/issues.rst | 0 2 files changed, 47 insertions(+) create mode 100644 doc/source/coverage.rst rename open_points => doc/source/issues.rst (100%) diff --git a/doc/source/coverage.rst b/doc/source/coverage.rst new file mode 100644 index 000000000..3c3e6d821 --- /dev/null +++ b/doc/source/coverage.rst @@ -0,0 +1,47 @@ +Service Coverage +================ + +Currently, the OTC Extensions cover 13 different services additionally +to the vanilla OpenStack services implemented in OpenStack SDK. Two +services (rds and cce) are currently covered in the documentation +under several service tags. This may change in future. + ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| ## | Service | Decription | CLI | GUI | PRX | RES | Comment | ++====+===============+==============================+=====+=====+=====+=====+=========+ +| 01 | anti_ddos | Anti-DDoS | X | . | X | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 02 | auto_scaling | Autoscaling | . | X | X | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 03 | cce | Cloud Container Engine | . | . | . | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 04 | cce_v1 | Cloud Container Engine | . | . | X | . | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 05 | cce_v2 | Cloud Container Engine | X | . | . | . | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 06 | cce_v3 | Cloud Container Engine | . | . | X | . | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 07 | cts | Cloud Trace Service | X | . | X | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 08 | dcs | Distributed Cache Service | X | . | X | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 09 | deh | Dedicated Host | X | X | X | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 10 | dms | Document Management Service | X | . | X | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 11 | dns | Domain Name Service | X | . | X | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 12 | kms | Key Management Service | X | . | X | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 13 | load_balancer | Load Balancer | X | . | . | . | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 14 | obs | Object Store | X | X | X | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 15 | rds | Relational Database Service | X | X | . | X | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 16 | rds_v1 | Relational Database Service | . | . | X | . | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 17 | rds_v3 | Relational Database Service | . | . | X | . | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ +| 18 | volume_backup | Volume Backup | X | X | X | . | | ++----+---------------+------------------------------+-----+-----+-----+-----+---------+ diff --git a/open_points b/doc/source/issues.rst similarity index 100% rename from open_points rename to doc/source/issues.rst From d7d6c92d09cced2b3c3247173f32fef97b972515 Mon Sep 17 00:00:00 2001 From: Nils-Magnus Date: Thu, 16 Jan 2020 02:30:46 +0100 Subject: [PATCH 04/42] collects all changes from previous commit, which was almost empty. --- doc/source/demo.rst-delme | 1 - doc/source/glossary.rst | 31 +++- doc/source/index.rst | 8 + doc/source/install/index.rst | 128 +++++++-------- doc/source/issues.rst | 215 +++++++++++++++++-------- doc/source/releasenotes.rst | 3 +- doc/source/save | 89 ---------- doc/source/user/guides/connect_otc.rst | 28 ++-- setup.cfg | 6 +- 9 files changed, 258 insertions(+), 251 deletions(-) delete mode 100644 doc/source/demo.rst-delme delete mode 100644 doc/source/save diff --git a/doc/source/demo.rst-delme b/doc/source/demo.rst-delme deleted file mode 100644 index 0f09d35b6..000000000 --- a/doc/source/demo.rst-delme +++ /dev/null @@ -1 +0,0 @@ -Ich bin hier diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst index ddae083ab..2bf09d6ee 100644 --- a/doc/source/glossary.rst +++ b/doc/source/glossary.rst @@ -107,9 +107,28 @@ Glossary Naming conventions ------------------ -OTC Extensions <- präferierte Schreibweise des Projekts -OTCE <- informelle Abkürzung, nicht in der offiziellen Dokumentation verwenden -otcextensions <- Name des Python-Package -python-otcextensions <- GitHub-Projektname -golang-otcextensions <- potenzielle anderes Projekt (= golang-gophercloud) -haskell-otcextensions +For consistency, a few naming conventions are defined for the name of +this project and adjacent identifiers. Let's start with the project +itself: + +`OTC Extensions`_ in exactly this spelling is the **name** of the +project. This term is used when the documentation references the +project as such. The three letters ``OTC`` are all uppercase. There is +a space and not dash between the two words. The second word is part of +the name and is thus capitalized. + +`otcextensions`_ is the name of the Python package hosted at +PyPI. Complying to the naming conventions of PyPI, the package name is +concatenated and consists only of lowercase letters. + +`python-otcextensions`_ is the name of the GitHub project where the +source code is hosted. It is the same name as the Python package, but +for compliance with many other OpenStack repositories, it is prepended +with ``python-`` as at least in theory there could also be a +``golang-otcextensions`` or even ``haskell-otcextensions`` project. + +.. _OTC Extensions: https://python-otcextensions.readthedocs.io/ + +.. _otcextensions: https://pypi.org/project/otcextensions/ + +.. _python-otcextensions: https://github.com/OpenTelekomCloud/python-otcextensions diff --git a/doc/source/index.rst b/doc/source/index.rst index 569b58957..046e32b4d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,6 +12,8 @@ Welcome to the OTC Extensions of the OpenStack SDK and CLI! History Glossary of Terms Release Notes + Service Coverage + Potential Issues Accessing the `OpenStack API`_ directly can be tedious. The `OpenStack SDK`_ is a Python based client library that simplifies building @@ -54,6 +56,10 @@ architecture. There is a `release history`_ available. +A list of `potential issues`_ is maintained. + +Currently 13 services are `covered` by the OTC extensions. + .. _OpenStack SDK: https://docs.openstack.org/openstacksdk/ .. _OpenStack API: https://openstack.org/api-ref/ .. _Open Telekom Cloud: https://open-telekom-cloud.com/ @@ -62,3 +68,5 @@ There is a `release history`_ available. .. _glossary: .. _history: .. _release history: +.. _potential issues: +.. _covered: diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 42dba52c7..4df5539f9 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -1,11 +1,10 @@ -============ Installation ============ -There are several ways to install python-otcextensions to enhance the native -``openstack`` CLI client and to extend the OpenStack SDK to cover the -additional Open Telekom Cloud services providing a larger functionality -on top of OpenStack. +There are several ways to install OTC Extensions to enhance the native +OpenStack Client and to extend the OpenStack SDK to cover the +additional Open Telekom Cloud services providing a larger +functionality on top of OpenStack. The easiest way is to use the Python pip installer which is working distribution independent and can be used in an isolated virtual environment @@ -21,22 +20,22 @@ https://build.opensuse.org/project/show/Cloud:OTC:Tools:OpenStack. Overview of Related Packages ---------------------------- -**OpenStackSDK:** +**OpenStack SDK:** A library on the client side that translates Python function calls into API calls to an OpenStack cloud. -**OpenStackClient:** -An application that turns the Python interface of OpenStackSDK and -python-otcextensions into a CLI tool. +**OpenStack Client:** +An application that turns the Python interface of OpenStack SDK and +OTC Extensions into a CLI tool. -**python-otcextensions:** -An addition to OpenStackSD with enhanced functionality that is specific for the -Open Telekom Cloud. +**OTC Extensions:** +An addition to OpenStack SDK with enhanced functionality that is specific for the +Open Telekom Cloud. This is the package you are currently looking at. Installation with pip installer ------------------------------- -All three packages are written in Python and stored as Python libraries in the +All three packages are written in Python and stored as Python packages in the PyPi repository. The following section describes the installation of ``OpenStackSDK``, ``otcextensions`` and ``OpenStackClient``. Please remember, it is not the latest development state. For this purpose the latest sources @@ -50,8 +49,8 @@ with developer libraries, and package manager pip are required: .. code-block:: bash - $ sudo apt update - $ sudo apt install gcc python3 python3-dev python3-pip libssl-dev + $ sudo apt update + $ sudo apt install gcc python3 python3-dev python3-pip libssl-dev Now, install all libraries and programs at once with the Python package manager pip. The --user flag provides user wide installation instead of a @@ -63,30 +62,28 @@ global installation. Installation under CentOS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^ For the installation, following packages are required: a C compiler, Python3 with developer libraries, and package manager pip are required. If you want to use python3 which is recommended, you need to install the epel repository, first: - .. code-block:: bash - $ sudo yum update - $ sudo yum install epel-release - $ sudo yum install gcc python36 python36-devel python36-pip openssl-devel - + $ sudo yum update + $ sudo yum install epel-release + $ sudo yum install gcc python36 python36-devel python36-pip openssl-devel Now, install all libraries and programs at once with the Python package manager pip: .. code-block:: bash - $ pip3 install otcextensions python-openstackclient --user + $ pip3 install otcextensions python-openstackclient --user Installation under Fedora -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^ For the installation, following packages are required: a C compiler, Python3 with developer libraries, and package manager pip are required: @@ -94,19 +91,19 @@ with developer libraries, and package manager pip are required: .. code-block:: bash - $ sudo dnf upgrade - $ sudo dnf install gcc python3 python3-devel python3-pip openssl-devel + $ sudo dnf upgrade + $ sudo dnf install gcc python3 python3-devel python3-pip openssl-devel Now, install all libraries and programs at once with the Python package manager pip: .. code-block:: bash - $ pip3 install otcextensions python-openstackclient --user + $ pip3 install otcextensions python-openstackclient --user -Installation in a virtual environment with pip installer --------------------------------------------------------------- +Installation in a virtual environment with the pip installer +------------------------------------------------------------ A virtual environment seperates your installed packages from other libraries and should be used as well. @@ -120,8 +117,8 @@ are required: .. code-block:: bash - $ sudo apt update - $ sudo apt install gcc python3 python3-dev python3-pip python3-venv libssl-dev + $ sudo apt update + $ sudo apt install gcc python3 python3-dev python3-pip python3-venv libssl-dev A virtual environment seperates your installed packages from other libraries and should be used as well. You can name the virtual environment on your own @@ -153,16 +150,16 @@ install the epel repository, first: .. code-block:: bash - $ sudo yum update - $ sudo yum install epel-release + $ sudo yum update + $ sudo yum install epel-release -No the python packages are needed: +No the Python packages are needed: .. code-block:: bash - $ sudo yum update - $ sudo yum install gcc python36 python36-devel python-pip \ - python-virtualenv openssl-devel + $ sudo yum update + $ sudo yum install gcc python36 python36-devel python-pip \ + python-virtualenv openssl-devel A virtual environment seperates your installed packages from other libraries and should be used as well. You can name the virtual environment on your own @@ -171,47 +168,46 @@ on "venv": .. code-block:: bash - $ python3 -m venv venv - $ source venv/bin/activate + $ python3 -m venv venv + $ source venv/bin/activate Now, install all libraries and programs at once with the Python package manager pip: .. code-block:: bash - $ pip install otcextensions openstackclient + $ pip install otcextensions openstackclient Installation under Fedora (under review) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the installation, following packages are required: a C compiler, Python3 with developer libraries, package manager, and a virtual environment are required: - .. code-block:: bash - $ sudo dnf upgrade - $ sudo dnf install gcc python3 python3-devel python3-pip \ - python3-virtualenv openssl-devel + $ sudo dnf upgrade + $ sudo dnf install gcc python3 python3-devel python3-pip \ + python3-virtualenv openssl-devel The virtual environment will be created and activated. You can name the virtual environment on your own desires, in our example it is "venv": .. code-block:: bash - $ python3 -m venv venv - $ source venv/bin/activate + $ python3 -m venv venv + $ source venv/bin/activate Now, install all libraries and programs at once with the Python package manager pip: .. code-block:: bash - (venv) $ pip install otcextensions openstackclient + (venv) $ pip install otcextensions openstackclient -Installation from Github sources +Installation from GitHub sources -------------------------------- The latest state of the packages can be installed with the following approach. @@ -220,7 +216,7 @@ Cloning the Github repository: .. code-block:: bash - $ git clone https://github.com/OpenTelekomCloud/python-otcextensions.git + $ git clone https://github.com/OpenTelekomCloud/python-otcextensions.git A virtual environment seperates your installed packages from other libraries and should be used as well. You can name the virtual environment on your own @@ -229,28 +225,28 @@ on "venv": .. code-block:: bash - $ python3 -m venv venv - $ source venv/bin/activate - (venv) $ + $ python3 -m venv venv + $ source venv/bin/activate + (venv) $ Switch into the new folder which is created by cloning the repository and install install the project dependencies into the virtual environment: .. code-block:: bash - (venv) $ cd ./python-otcextensions + (venv) $ cd ./python-otcextensions Register the CLI plugin using: .. code-block:: bash - (venv) ~/python-otcextensions$ python setup.py install + (venv) ~/python-otcextensions$ python setup.py install Install Openstack-Client binary from pip-Repository: .. code-block:: bash - (venv) ~/python-otcextensions$ pip install openstackclient + (venv) ~/python-otcextensions$ pip install openstackclient Configuration for the Cloud Connection -------------------------------------- @@ -328,7 +324,7 @@ Use the following command to test the basic functionality. .. code-block:: bash - $ openstack --os-cloud otc flavor list + $ openstack --os-cloud otc flavor list Splitting the credentials in clouds.yaml and secure.yaml ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -373,15 +369,15 @@ according to your credentials. .. code-block:: bash - export OS_AUTH_URL= - export OS_IDENTITY_API_VERSION=3 - export OS_PROJECT_NAME= - export OS_PROJECT_DOMAIN_NAME= - export OS_USERNAME= - export OS_USER_DOMAIN_NAME= - export OS_PASSWORD= # (optional) - export S3_ACCESS_KEY_ID= - export S3_SECRET_ACCESS_KEY= + $ export OS_AUTH_URL= + $ export OS_IDENTITY_API_VERSION=3 + $ export OS_PROJECT_NAME= + $ export OS_PROJECT_DOMAIN_NAME= + $ export OS_USERNAME= + $ export OS_USER_DOMAIN_NAME= + $ export OS_PASSWORD= # (optional) + $ export S3_ACCESS_KEY_ID= + $ export S3_SECRET_ACCESS_KEY= Test your connection ^^^^^^^^^^^^^^^^^^^^ @@ -390,4 +386,4 @@ Use the following command to test the basic functionality. .. code-block:: bash - $ openstack flavor list + $ openstack flavor list diff --git a/doc/source/issues.rst b/doc/source/issues.rst index 2953d9c25..98c6b99c6 100644 --- a/doc/source/issues.rst +++ b/doc/source/issues.rst @@ -1,125 +1,200 @@ -This document gathers issues, which are found during diggint the API and other OS tools working with API - -* on 28.03 native service version discovery request to https://as.eu-de.otc.t-systems.com/autoscaling-api/ caused timeout. AS service is temporarily disabled - -# General: - -* Inconsistent naming between services (AS:create_time, KMS:creation_date, CCE:createAt) -* Inconsistent error message structure between services (i.e. KMS vs RDS). This prohibits code generalization -* No custom service supports proper version discovery. Leads to error messages in the OSC tool and execution delays -* LB: while Neutron LBaaS is "strongly" considered as deprecated and no bindings are present in Ansible/OSC - it will likely not be possible/challenge to upstream this support. +Known Issues +============ + +Since providing services and writing client libraries is decoupled, +sometimes issues arise due to errors in the client or the server side, +or due to a service disruption or degration. This page collects +potential issues. They have been found during digging into the API. + +General +------- + +* Native service version discovery request to + https://as.eu-de.otc.t-systems.com/autoscaling-api/ caused + timeout. AS service is temporarily disabled +* Inconsistent naming between services (AS:create_time, + KMS:creation_date, CCE:createAt) +* Inconsistent error message structure between services (i.e. KMS vs + RDS). This prohibits code generalization +* No custom service supports proper version discovery. Leads to error + messages in the OSC tool and execution delays +* LB: while Neutron LBaaS is "strongly" considered as deprecated and + no bindings are present in Ansible/OSC it will likely not be + possible/challenge to upstream this support. * EVS: volume type list --long returns changing results * Subnet (in some APIs) is most likely net_id -* Without service discovery and multiple versions it is not possible to get the proper service version in SDK. It falls back to first entry in the VersionFilter +* Without service discovery and multiple versions it is not possible + to get the proper service version in SDK. It falls back to first + entry in the VersionFilter * Tags require different format ("key=value" vs "key*value") -# KMS: - -* service version discovery is broken. On https://kms.eu-de.otc.t-systems.com/ it returns - {"versions": [{"status": "CURRENT", "id": "v1.0", "links": [{"href": "https://rts.eu-de.otc.t-systems.com/v1/", "rel": "self"}]}]} - In the keystoneauth1 it results to get_endpoint=https://kms.eu-de.otc.t-systems.com/v1 (instead of V1.0). Detailed investigation is expensive, therefore aborted -* does not follow REST, everything is POST with different URLs and not even json['action'] +KMS +--- + +* service version discovery is broken. On + https://kms.eu-de.otc.t-systems.com/ it returns {"versions": + [{"status": "CURRENT", "id": "v1.0", "links": [{"href": + "https://rts.eu-de.otc.t-systems.com/v1/", "rel": "self"}]}]} In the + keystoneauth1 it results to + get_endpoint=https://kms.eu-de.otc.t-systems.com/v1 (instead of + V1.0). Detailed investigation is expensive, therefore aborted +* does not follow REST, everything is POST with different URLs and not + even json['action'] * is conceptually far away from Barbican -* API Doc: This API allows you to create a plaintext-free DEK, that is, the returned result of this API includes `only the plaintext` of the DEK. -* purpose of KMS is not precise. Attributes change their names/meaning depending on call -* encryption_context is described to be string, in reality dict is expected -* max_length is always expected to be exactly max. Make no sense as a param +* API Doc: This API allows you to create a plaintext-free DEK, that + is, the returned result of this API includes `only the plaintext` of + the DEK. +* purpose of KMS is not precise. Attributes change their names/meaning + depending on call +* encryption_context is described to be string, in reality dict is + expected +* max_length is always expected to be exactly max. Make no sense as a + param * list CMK filter by key_state not working as documented * format of the timestamp is unknown * no way to get response in English -# CCE +CCE +--- * required header application/type also for GET -* cluster UUID is hidden in a inline metadata structure, making it hard to address it without dirty hacks. - Apis are jumping through this structure in anti-rest pattern +* cluster UUID is hidden in a inline metadata structure, making it + hard to address it without dirty hacks. Apis are jumping through + this structure in anti-rest pattern * attribute naming: metadata.uuid vs metadata.uid * undocumented properties of the cluster.spec field (i.e. `cidr`) * far away from Magnum -* Cluster has both VPC and VPC_ID, in GET VPC is name, in POST it should be ID +* Cluster has both VPC and VPC_ID, in GET VPC is name, in POST it + should be ID * Subnet is most likely net_id * In AS sys disk has type "SYS", in CCE - "root" * Node delete possible only by name, and not id -* service catalog configuration is broken v1 vs v2(v3) with no corrupted discovery and new service type +* service catalog configuration is broken v1 vs v2(v3) with no + corrupted discovery and new service type -# DCS: +DCS +--- -* DCS: in OS DCS is part of Trove. The API is same. In the DCS API is similar to RDS, but not easy mappable -* DCS: Since Redis 3.0.7 (only available in DCS) lots of critical issues (incl. security and possible data corruption), online memory defrag, less mem usage were fixed +* In OS DCS is part of Trove. The API is same. In the DCS API is + similar to RDS, but not easy mappable +* Since Redis 3.0.7 (only available in DCS) lots of critical issues + (incl. security and possible data corruption), online memory defrag, + less mem usage were fixed + +MRS +--- -# MRS: * Inconsistent naming between services ( data_processing-mrs ) -# OBS: +OBS +--- -* OBS has storage class on Bucket level, but in AWS and all corresponding tools (also s3cmd, s4cmd, Boto) it is on the Object level +* Has storage class on Bucket level, but in AWS and all corresponding + tools (also s3cmd, s4cmd, Boto) it is on the Object level -# DNS (Designate): +DNS (Designate) +--------------- -* nothing supports private zone (ansible, heat, ~terraform, SDK/CLI). Very hard to cover that everywhere -* Zone transfer, slave zone are not present. Modern Designateclient is not getting clear with response of designate +* Nothing supports private zone (ansible, heat, ~terraform, + SDK/CLI). Very hard to cover that everywhere +* Zone transfer, slave zone are not present. Modern Designateclient is + not getting clear with response of designate * API v2 is not implemented -# VBS: +VBS +--- -* uses offset as a pagination, instead of marker (in docs, in reality marker is supported) -* backup creation takes too long. 1Gb empty volume takes >4 minutes. Functional tests are not reasonable with that. -* create policy requires frequency to be set -* shift implemented stuff to osc +* Uses offset as a pagination, instead of marker (in docs, in reality + marker is supported) +* Backup creation takes too long. 1Gb empty volume takes >4 + minutes. Functional tests are not reasonable with that. +* Create policy requires frequency to be set +* Shift implemented stuff to osc -# CSS: +CSS +--- * upon creation httpsEnable is str, upon read - bool * flavors is not OpenStack compatible -# HEAT: - -* very old level, blocking many OpenSource projects, including i.e. ansible-openshift, RedhatDNS. -* (to be doublechecked) template version check is likely not done, since features of later templates with older version header are passing validation (in the ranges of supported versions) -* validate return ok, doesn't mean create will pass (validation errors i.e. template version doesn't match, condition on a resource level was also added on newton) +HEAT +---- + +* very old level, blocking many OpenSource projects, including + i.e. ansible-openshift, RedhatDNS. +* (to be doublechecked) template version check is likely not done, + since features of later templates with older version header are + passing validation (in the ranges of supported versions) +* validate return ok, doesn't mean create will pass (validation errors + i.e. template version doesn't match, condition on a resource level + was also added on newton) * not all CLI calls return result -* Not possible to rely on mountpoint of the OS::Cinder::VolumeAttachment - it's ignored -* usage of Server with block_device_mapping_v2, devicename="sdX" and > 1 device fails. Port is not released leaving system in inconsistent state (if router interface is deleted can be cleaned only manually) -* OS::Neutron::LBaaS::HealthMonitor does not support type HTTPS, but GUI allows it +* Not possible to rely on mountpoint of the + OS::Cinder::VolumeAttachment - it's ignored +* usage of Server with block_device_mapping_v2, devicename="sdX" and > + 1 device fails. Port is not released leaving system in inconsistent + state (if router interface is deleted can be cleaned only manually) +* OS::Neutron::LBaaS::HealthMonitor does not support type HTTPS, but + GUI allows it * update stack with existing template is missing -# Shade/Ansible: - -* enabling SNAT through Ansible not possible, since upstream expects default as true and sends only false if set (shade:_build_external_gateway_info) -* only able to pass SYS volume size if boot_from_volume=True (default=false) -* on a play retry port in the subnet changes if exists (change IP) and corrupts connection -* Ansible: no support for load balancer -* Ansible (Heat): https://github.com/ansible/ansible/issues/30786 - small fix to see the failure message if stack create/update fails -* Private: yes helps to get public_v4 filled, but it hinders create request with auto_ip:true +Shade/Ansible +------------- + +* enabling SNAT through Ansible not possible, since upstream expects + default as true and sends only false if set + (shade:_build_external_gateway_info) +* only able to pass SYS volume size if boot_from_volume=True + (default=false) +* on a play retry port in the subnet changes if exists (change IP) and + corrupts connection +* No support for load balancer +* Ansible (Heat): https://github.com/ansible/ansible/issues/30786 - + small fix to see the failure message if stack create/update fails +* Private: yes helps to get public_v4 filled, but it hinders create + request with auto_ip:true * add router interface -# VPC: +VPC +--- -* VPC uses network wrapped subnets. Simple net with multiple subnets is not properly visible in OTC (in VPCs list subnet count includes all subnets, but in VPC show subnets are missing) +* VPC uses network wrapped subnets. Simple net with multiple subnets + is not properly visible in OTC (in VPCs list subnet count includes + all subnets, but in VPC show subnets are missing) -# TMS: +TMS +--- * How to assign tag to resource from API? -# BMS: +BMS +--- * it is not Ironic, but ECS -# Network: +Network +------- -* SecGroup rule "Any" (value=0) is not working as designed. OSC uses defaults, use of 0 results in really 0 as a value. Effect is unknown yet +* Security Group rule "Any" (value=0) is not working as designed. OSC + uses defaults, use of 0 results in really 0 as a value. Effect is + unknown yet -# DeH +DeH +--- * Tag support is not OS compatible -# OpenStackSDK: +OpenStack SDK +------------- -* LBaaS: pool.healthmonitor_id according to ref api (and in OTC), but in the SDK it is health_monitor_ids (list) (reported under https://storyboard.openstack.org/#!/story/2001872). Some other attributes missing - - pool_member operating_status missing +* LBaaS: pool.healthmonitor_id according to ref api (and in OTC), but + in the SDK it is health_monitor_ids (list) (reported under + https://storyboard.openstack.org/#!/story/2001872). Some other + attributes missing. pool_member operating_status missing * LBaaS HM: max_retries_down missing (optional and not present in OTC) +DOC +--- -# DOC: -* at least on example of ULB LIST allows filtering, but it is not documented +* at least on example of ULB LIST allows filtering, but it is not + documented diff --git a/doc/source/releasenotes.rst b/doc/source/releasenotes.rst index 74fa320f0..d9adcb965 100644 --- a/doc/source/releasenotes.rst +++ b/doc/source/releasenotes.rst @@ -1,5 +1,4 @@ -============= Release Notes ============= -Release notes for `python-otcextensions` are currently not implemented +Release notes for are currently not implemented for OTC Extensions. diff --git a/doc/source/save b/doc/source/save deleted file mode 100644 index 579299a6d..000000000 --- a/doc/source/save +++ /dev/null @@ -1,89 +0,0 @@ -Welcome to the OTC Extensions of the OpenStack SDK and CLI! -=========================================================== - -OTC Extensions <- präferierte Schreibweise des Projekts -OTCE <- informelle Abkürzung, nicht in der offiziellen Dokumentation verwenden -otcextensions <- Name des Python-Package -python-otcextensions <- GitHub-Projektname -golang-otcextensions <- potenzielle anderes Projekt (= golang-gophercloud) -haskell-otcextensions - -Accessing the `OpenStack API`_ can be tedious. The `OpenStack SDK`_ is -a Python based programming library that simplifies using that API. -This project, OTC Extensions, augments this SDK and adds extra -functionality offered by the `Open Telekom Cloud`_. The OTC Extensions -serve two purposes: Firstly, they provide Python classes and methods -to attach your own code to the cloud. For example, `Ansible modules`_ -use this way. Secondly, the OTC Extensions automatically extend the -`OpenStack Client`_, the CLI tool to manage the OpenStack cloud. - -This documentation is split into four sections, adressing several use -cases: - -* The :doc:`installation ` guide explains system - administrators and developers how to setup the project from - operation system packages, from pip, directly from sources and other - installation forms. **** Configuration **** - -* Users who want to access Open Telekom Cloud specific services with - :doc:`command line tools ` find documentation of all of - their opetions and properties in this section. - -* Developers, who plan to write own Python code, may access the API - more easily by using the OTC Extensions' classes and methods. The - :doc:`architecture and interfaces ` are documented in - this section. - -* Developers, who want to :doc:`contribute ` to the - project find helpful background information. - - -Installation ------------- - -.. toctree:: - :maxdepth: 2 - - install/index - -CLI Usage ---------- - -This guides give you an overview of the CLI commands - -.. toctree:: - :maxdepth: 2 - - cli/index - -For Users ---------- - -.. toctree:: - :maxdepth: 2 - - user/index - -For Contributors ----------------- - -.. toctree:: - :maxdepth: 2 - - contributor/index - -General Information -------------------- - -General information about the SDK including a glossary and release history. - -.. toctree:: - :maxdepth: 1 - - Glossary of Terms - Release Notes - Ressources - -# Links references by the text above: - -.. _OpenStack SDK: https://docs.openstack.org/openstacksdk/latest/ diff --git a/doc/source/user/guides/connect_otc.rst b/doc/source/user/guides/connect_otc.rst index d0e27ac67..e7a7b7398 100644 --- a/doc/source/user/guides/connect_otc.rst +++ b/doc/source/user/guides/connect_otc.rst @@ -1,13 +1,16 @@ -Connect OTC -=========== +Connect to the cloud +==================== In order to work with an OpenStack cloud you first need to create a -:class:`~openstack.connection.Connection` to it using your credentials. A -:class:`~openstack.connection.Connection` can be -created in 3 ways, using the class itself, :ref:`config-clouds-yaml`, or -:ref:`config-environment-variables`. It is recommended to always use -:ref:`config-clouds-yaml` as the same config can be used across tools and -languages. +:class:`~openstack.connection.Connection` using your credentials. A +:class:`~openstack.connection.Connection` can be created in three +ways, using the class itself, :ref:`config-clouds-yaml`, or +:ref:`config-environment-variables`. It is recommended use +:ref:`config-clouds-yaml` as the same config can be used across tools +and languages. Examples are the OpenStack Client, the Gophercloud +library for golang, and Terraform that is based on that +library. Please be also aware that environment variables carrying +credentials can be a security risk. Create Connection ----------------- @@ -15,7 +18,7 @@ Create Connection To create a :class:`~openstack.connection.Connection` instance, use the :func:`~openstack.connect` factory function. -As a next step inject the OTC extensions into the retrieved connection +As a next step inject the OTC Extensions into the retrieved connection .. code-block:: python @@ -25,15 +28,12 @@ As a next step inject the OTC extensions into the retrieved connection # Register OTC Extensions sdk.register_otc_extensions(conn) -Full example at `connect_otc.py `_ +See a full example at `connect_otc.py `_ .. note:: To enable logging, see the :doc:`logging` user guide. Next ---- + Now that you can create a connection, continue with the :ref:`user_guides` to work with an OpenStack service. - -.. TODO(shade) Update the text here and consolidate with the old - os-client-config docs so that we have a single and consistent explanation - of the envvars cloud, etc. diff --git a/setup.cfg b/setup.cfg index 65555cce7..a03f17c21 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,11 +1,11 @@ [metadata] name = otcextensions -summary = OpenStack Command-line Client and SDK Extensions for OpenTelekomCloud +summary = Open Telekom Cloud specific extensions for the OpenStack Client CLI and OpenStack SDK description-file = README.rst author = Artem Goncharov author-email = artem.goncharov@gmail.com -home-page = http://python-otcextensions.readthedocs.io/en/latest/ +home-page = http://python-otcextensions.readthedocs.io/ classifier = Environment :: OpenStack Intended Audience :: Information Technology @@ -19,7 +19,7 @@ classifier = Programming Language :: Python :: 3.6 Programming Language :: Python :: 3.7 keywords = - OpenStack, openstackclient, openstacksdk, OpenTelekomCloud, otc, t-systems, telekom + OpenStack, openstackclient, openstacksdk, Open Telekom Cloud, otc, T-Systems, Telekom [files] packages = From 5017363bcb3353132f4ffaa966c305024a41acde Mon Sep 17 00:00:00 2001 From: Nils Magnus Date: Thu, 23 Jan 2020 07:54:33 +0100 Subject: [PATCH 05/42] enhances the structure of two index files --- doc/source/index.rst | 119 +++++++++++++++++++++++++------------- doc/source/user/index.rst | 44 +++++++++----- 2 files changed, 109 insertions(+), 54 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 046e32b4d..9fdf2311e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,67 +1,104 @@ Welcome to the OTC Extensions of the OpenStack SDK and CLI! =========================================================== -.. toctree:: - :includehidden: - :maxdepth: 1 - - Installation - CLI Usage - Package Reference - Contributing - History - Glossary of Terms - Release Notes - Service Coverage - Potential Issues - Accessing the `OpenStack API`_ directly can be tedious. The `OpenStack SDK`_ is a Python based client library that simplifies building -applications to work with OpenStack clouds. This project, OTC -Extensions, augments this SDK and adds extra functionality offered by -the `Open Telekom Cloud`_. The OTC Extensions serve two purposes: +applications to work with OpenStack clouds. **This project, OTC +Extensions,** augments this SDK and adds extra functionality offered +by the `Open Telekom Cloud`_. The OTC Extensions serve two purposes: Firstly, they provide Python classes and methods to attach your own code to the cloud. For example, `Ansible modules`_ use this way. Secondly, the OTC Extensions automatically extend the `OpenStack Client`_, the CLI tool to manage the OpenStack cloud. -This documentation is split into four sections, adressing several use -cases: +Content +------- + +This documentation is split into four sections, adressing major use +cases. Additionally some auxiliary documentation is available: + +.. toctree:: + :includehidden: + :numbered: + :maxdepth: 1 + + install/index + cli/index + user/index + contributor/index + history + glossary + releasenotes + coverage + issues + +1 Installation +2 CLI Usage +3 Package Reference +4 Contributing +5 History +6 Glossary of Terms +7 Release Notes +8 Service Coverage +9 Potential Issues -* The :doc:`installation ` guide explains system - administrators and developers how to setup the project from - operation system packages, from pip, directly from sources and other - installation forms. Configuration -* Users who want to access Open Telekom Cloud specific services with - :doc:`command line tools ` find documentation of all of - their opetions and properties in this section. +Installation and Configuration +------------------------------ + +The :doc:`installation ` guide explains system +administrators and developers how to setup the project from operation +system packages, from pip, directly from sources and other +installation forms. OTC Extensions are very easy to configure: All +credentials can be configured in one or two files. + + +Working with the CLI tool +------------------------- + +Users who want to access Open Telekom Cloud specific services with +:doc:`command line tools ` for a shell like Bash find +documentation of all of their opetions and properties in this section. + + +Writing your own Scripts for the Cloud +-------------------------------------- + +Developers, who plan to write own Python code, may access the API more +easily by using the OTC Extensions' classes and methods. The +:doc:`architecture and interfaces ` are documented in this +section. + + +Contribute to the Project +------------------------- + +Developers, who want to :doc:`contribute ` to the +project, find helpful background information and architecture +specification of OTC Extensions here. -* Developers, who plan to write own Python code, may access the API - more easily by using the OTC Extensions' classes and methods. The - :doc:`architecture and interfaces ` are documented in - this section. - -* Developers, who want to :doc:`contribute ` to the - project find helpful background information. General Information ------------------- -In a `glossary`_ important terms and their naming conventions are described. +Adding to that, there is some general background information +available: + +* In a `glossary`_ important terms and their naming conventions are + described. -There is a `history`_ explaing the ancestry of this project. This may -or may not be insightful if you want to understand the projects -architecture. +* There is a `history`_ explaing the ancestry of this project. This + may or may not be insightful if you want to understand the projects + architecture. -There is a `release history`_ available. +* There is a `release history`_ available. -A list of `potential issues`_ is maintained. +* A list of `potential issues`_ is maintained. -Currently 13 services are `covered` by the OTC extensions. +* Currently 13 services are `covered`_ by the OTC extensions. .. _OpenStack SDK: https://docs.openstack.org/openstacksdk/ -.. _OpenStack API: https://openstack.org/api-ref/ +.. _OpenStack API: https://docs.openstack.org/api-quick-start/ .. _Open Telekom Cloud: https://open-telekom-cloud.com/ .. _Ansible modules: https://github.com/OpenTelekomCloud/ansible-collections/ .. _OpenStack Client: https://docs.openstack.org/python-openstackclient/ diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index ea53594d7..223f6d000 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,9 +1,9 @@ -Getting started with the OTCExtensions SDK -========================================== +Getting started with the OTC Extensions +======================================= -The SDK/OTCE contain an abstraction interface layer. Clouds can do many -things, but there are probably only about 10 of them that most people -care about with any regularity. +The OTC Extensions contain an abstraction interface layer. Clouds can +do many things, but there are probably only about 10 of them that most +people care about with any regularity. If you want to do complicated things, the per-service oriented portions of the SDK are for you. @@ -13,20 +13,38 @@ talks to clouds no matter what crazy choices the deployer has made in an attempt to be more hipster than their self-entitled narcissist peers, then the Cloud Abstraction layer is for you. +Please note that OTC Extensions provides an extension to the +OpenStackSDK. Please refer to it's documentation for the details + -Please note that OTCExtensions provides an extension to the OpenStackSDK. -Please refer to it's documentation for the details +Verify Installation +------------------- +You need to have the OpenStack SDK in package `openstacksdk` installed +to work with the OTC Extensions, which are packaged in +`otcextensions`. Thanks to a plugin mechanism, no additional +configuration is needed to use the extension. To verify you are up and +running write a file `demo.py`: -Installation ------------- +.. code-block: python -The OTCExtensions SDK is available on -`GitHub `_. -To install it, use ``pip``:: + import openstack as mycloud - $ pip install otcextensions + conn = mycloud.connect("otc") + conn.jjjjj.flavors() + +Make sure that you configured your credentials as describe in the +`configuration` section. Run this script with + +.. code-block: bash + $ python demo.py + +It should XXXXXXXX list your XXXXXXXX. + + +with this Python script and run it with +`python demo.py`. .. _user_guides: From a72663cd9581ce34adf78ca705a1cd8a0a688235 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Thu, 5 Mar 2020 15:44:37 +0000 Subject: [PATCH 06/42] Installation and Configuration sources resorted --- doc/source/index.rst | 1 + doc/source/install/configuration.rst | 139 ++++++++++ doc/source/install/index.rst | 359 +------------------------- doc/source/install/pip_install.rst | 175 +++++++++++++ doc/source/install/source_install.rst | 40 +++ 5 files changed, 361 insertions(+), 353 deletions(-) create mode 100644 doc/source/install/configuration.rst create mode 100644 doc/source/install/pip_install.rst create mode 100644 doc/source/install/source_install.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 9fdf2311e..d26578199 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -23,6 +23,7 @@ cases. Additionally some auxiliary documentation is available: :maxdepth: 1 install/index + install/configuration cli/index user/index contributor/index diff --git a/doc/source/install/configuration.rst b/doc/source/install/configuration.rst new file mode 100644 index 000000000..c9e5b1b01 --- /dev/null +++ b/doc/source/install/configuration.rst @@ -0,0 +1,139 @@ +Configuration for the Cloud Connection +====================================== + +You can connect to the Open Telekom Cloud and OpenStack clouds in general +using two approaches. The first one uses a credential file called +``clouds.yaml`` and the other one is to use environment variables. + +Configuring a clouds.yaml file +------------------------------ + +The credential file clouds.yaml will be queried automatically in different +locations with increasing precedence: + +1. system-wide (/etc/openstack/{clouds,secure}.yaml) +2. Home directory / user space (~/.config/openstack/{clouds,secure}.yaml) +3. Current directory (./{clouds,secure}.yaml) + +A sample clouds.yaml file is listed below to connect with Open Telekom Cloud: + +**clouds.yaml** + +.. code-block:: yaml + + clouds: + otc: + auth: + username: 'USER_NAME' + password: 'PASS' + 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 # !Important + ak: 'AK_VALUE' # AK/SK pair for access to OBS + sk: 'SK_VALUE' + +The name otc is self-defined and can be changed. AK/SK values required for +access to some services (i.e. OBS) can be either configured as shown above +in the clouds.yaml/secure.yaml, or they can be automatically retrieved from +the S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY. + +Additional connections to other Openstack-clouds or -projects can be added +to the file as shown below: + +**clouds.yaml** + +.. code-block:: yaml + + clouds: + otc: + auth: + username: 'USER_NAME' + password: 'PASS' + 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 # !Important + ak: 'AK_VALUE' # AK/SK pair for access to OBS + sk: 'SK_VALUE' + otcsecondproject: + region_name: eu-de + auth: + username: '' + password: '' + project_id: '' + user_domain_id: '' + auth_url: 'https://iam.eu-de.otc.t-systems.com:443/v3' + +Test your connection +^^^^^^^^^^^^^^^^^^^^ + +Use the following command to test the basic functionality. + +.. code-block:: bash + + $ openstack --os-cloud otc flavor list + +Splitting the credentials in clouds.yaml and secure.yaml +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In some scenarios a split of security credentials from the configuration file +is necessary. The optional file ``secure.yaml`` can be used to store the +secret which is left out from ``clouds.yaml``: + +**clouds.yaml** + +.. code-block:: yaml + + clouds: + otc: + auth: + username: 'USER_NAME' + 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 # !Important + ak: 'AK_VALUE' # AK/SK pair for access to OBS + sk: 'SK_VALUE' + +**secure.yaml** + +.. code-block:: yaml + + clouds: + otc: + auth: + password: '' + +Configuration of Environment Variables +-------------------------------------- + +Instead of using the clouds.yaml file, environmnt variables can be configured +to connect to the Open Telekom Cloud. Create a simple file like ``.ostackrc`` +in the home directory and source the file to make the variables available. On +Open Telekom Cloud servers this file exists on bootup and needs to be changed +according to your credentials. + +.. code-block:: bash + + $ export OS_AUTH_URL= + $ export OS_IDENTITY_API_VERSION=3 + $ export OS_PROJECT_NAME= + $ export OS_PROJECT_DOMAIN_NAME= + $ export OS_USERNAME= + $ export OS_USER_DOMAIN_NAME= + $ export OS_PASSWORD= # (optional) + $ export S3_ACCESS_KEY_ID= + $ export S3_SECRET_ACCESS_KEY= + +Test your connection +^^^^^^^^^^^^^^^^^^^^ + +Use the following command to test the basic functionality. + +.. code-block:: bash + + $ openstack flavor list diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 4df5539f9..fce37b0ad 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -32,358 +32,11 @@ OTC Extensions into a CLI tool. An addition to OpenStack SDK with enhanced functionality that is specific for the Open Telekom Cloud. This is the package you are currently looking at. -Installation with pip installer -------------------------------- +Content +------- -All three packages are written in Python and stored as Python packages in the -PyPi repository. The following section describes the installation of -``OpenStackSDK``, ``otcextensions`` and ``OpenStackClient``. Please remember, -it is not the latest development state. For this purpose the latest sources -needs to be installed. +.. toctree:: + :maxdepth: 3 -Installation under Ubuntu or Debian -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, and package manager pip are required: - -.. code-block:: bash - - $ sudo apt update - $ sudo apt install gcc python3 python3-dev python3-pip libssl-dev - -Now, install all libraries and programs at once with the Python package -manager pip. The --user flag provides user wide installation instead of a -global installation. - -.. code-block:: bash - - $ pip3 install otcextensions python-openstackclient --user - - -Installation under CentOS -^^^^^^^^^^^^^^^^^^^^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, and package manager pip are required. If you want to -use python3 which is recommended, you need to install the epel -repository, first: - -.. code-block:: bash - - $ sudo yum update - $ sudo yum install epel-release - $ sudo yum install gcc python36 python36-devel python36-pip openssl-devel - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - $ pip3 install otcextensions python-openstackclient --user - -Installation under Fedora -^^^^^^^^^^^^^^^^^^^^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, and package manager pip are required: - - -.. code-block:: bash - - $ sudo dnf upgrade - $ sudo dnf install gcc python3 python3-devel python3-pip openssl-devel - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - $ pip3 install otcextensions python-openstackclient --user - - -Installation in a virtual environment with the pip installer ------------------------------------------------------------- - -A virtual environment seperates your installed packages from other -libraries and should be used as well. - -Installation under Ubuntu or Debian -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, package manager, and virtual environment -are required: - -.. code-block:: bash - - $ sudo apt update - $ sudo apt install gcc python3 python3-dev python3-pip python3-venv libssl-dev - -A virtual environment seperates your installed packages from other libraries -and should be used as well. You can name the virtual environment on your own -desires, in our example it is: "venv". The second command will switch -on "venv": - -.. code-block:: bash - - $ python3 -m venv venv - $ source venv/bin/activate - (venv) $ - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - $ pip install otcextensions openstackclient - - -Installation under CentOS -^^^^^^^^^^^^^^^^^^^^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, package manager, and virtual environment are -required. If you want to use python3 which is recommended, you need to -install the epel repository, first: - - -.. code-block:: bash - - $ sudo yum update - $ sudo yum install epel-release - -No the Python packages are needed: - -.. code-block:: bash - - $ sudo yum update - $ sudo yum install gcc python36 python36-devel python-pip \ - python-virtualenv openssl-devel - -A virtual environment seperates your installed packages from other libraries -and should be used as well. You can name the virtual environment on your own -desires, in our example it is: "venv". The second command will switch -on "venv": - -.. code-block:: bash - - $ python3 -m venv venv - $ source venv/bin/activate - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - $ pip install otcextensions openstackclient - -Installation under Fedora (under review) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For the installation, following packages are required: a C compiler, -Python3 with developer libraries, package manager, and a virtual -environment are required: - -.. code-block:: bash - - $ sudo dnf upgrade - $ sudo dnf install gcc python3 python3-devel python3-pip \ - python3-virtualenv openssl-devel - -The virtual environment will be created and activated. You can name the -virtual environment on your own desires, in our example it is "venv": - -.. code-block:: bash - - $ python3 -m venv venv - $ source venv/bin/activate - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - (venv) $ pip install otcextensions openstackclient - - -Installation from GitHub sources --------------------------------- - -The latest state of the packages can be installed with the following approach. - -Cloning the Github repository: - -.. code-block:: bash - - $ git clone https://github.com/OpenTelekomCloud/python-otcextensions.git - -A virtual environment seperates your installed packages from other libraries -and should be used as well. You can name the virtual environment on your own -desires, in our example it is: "venv". The second command will switch -on "venv": - -.. code-block:: bash - - $ python3 -m venv venv - $ source venv/bin/activate - (venv) $ - -Switch into the new folder which is created by cloning the repository and -install install the project dependencies into the virtual environment: - -.. code-block:: bash - - (venv) $ cd ./python-otcextensions - -Register the CLI plugin using: - -.. code-block:: bash - - (venv) ~/python-otcextensions$ python setup.py install - -Install Openstack-Client binary from pip-Repository: - -.. code-block:: bash - - (venv) ~/python-otcextensions$ pip install openstackclient - -Configuration for the Cloud Connection --------------------------------------- - -You can connect to the Open Telekom Cloud and OpenStack clouds in general -using two approaches. The first one uses a credential file called -``clouds.yaml`` and the other one is to use environment variables. - -Configuring a clouds.yaml file -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The credential file clouds.yaml will be queried automatically in different -locations with increasing precedence: - -1. system-wide (/etc/openstack/{clouds,secure}.yaml) -2. Home directory / user space (~/.config/openstack/{clouds,secure}.yaml) -3. Current directory (./{clouds,secure}.yaml) - -A sample clouds.yaml file is listed below to connect with Open Telekom Cloud: - -**clouds.yaml** - -.. code-block:: yaml - - clouds: - otc: - auth: - username: 'USER_NAME' - password: 'PASS' - 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 # !Important - ak: 'AK_VALUE' # AK/SK pair for access to OBS - sk: 'SK_VALUE' - -The name otc is self-defined and can be changed. AK/SK values required for -access to some services (i.e. OBS) can be either configured as shown above -in the clouds.yaml/secure.yaml, or they can be automatically retrieved from -the S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY. - -Additional connections to other Openstack-clouds or -projects can be added -to the file as shown below: - -**clouds.yaml** - -.. code-block:: yaml - - clouds: - otc: - auth: - username: 'USER_NAME' - password: 'PASS' - 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 # !Important - ak: 'AK_VALUE' # AK/SK pair for access to OBS - sk: 'SK_VALUE' - otcsecondproject: - region_name: eu-de - auth: - username: '' - password: '' - project_id: '' - user_domain_id: '' - auth_url: 'https://iam.eu-de.otc.t-systems.com:443/v3' - -Test your connection -^^^^^^^^^^^^^^^^^^^^ - -Use the following command to test the basic functionality. - -.. code-block:: bash - - $ openstack --os-cloud otc flavor list - -Splitting the credentials in clouds.yaml and secure.yaml -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In some scenarios a split of security credentials from the configuration file -is necessary. The optional file ``secure.yaml`` can be used to store the -secret which is left out from ``clouds.yaml``: - -**clouds.yaml** - -.. code-block:: yaml - - clouds: - otc: - auth: - username: 'USER_NAME' - 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 # !Important - ak: 'AK_VALUE' # AK/SK pair for access to OBS - sk: 'SK_VALUE' - -**secure.yaml** - -.. code-block:: yaml - - clouds: - otc: - auth: - password: '' - -Configuration of Environment Variables --------------------------------------- - -Instead of using the clouds.yaml file, environmnt variables can be configured -to connect to the Open Telekom Cloud. Create a simple file like ``.ostackrc`` -in the home directory and source the file to make the variables available. On -Open Telekom Cloud servers this file exists on bootup and needs to be changed -according to your credentials. - -.. code-block:: bash - - $ export OS_AUTH_URL= - $ export OS_IDENTITY_API_VERSION=3 - $ export OS_PROJECT_NAME= - $ export OS_PROJECT_DOMAIN_NAME= - $ export OS_USERNAME= - $ export OS_USER_DOMAIN_NAME= - $ export OS_PASSWORD= # (optional) - $ export S3_ACCESS_KEY_ID= - $ export S3_SECRET_ACCESS_KEY= - -Test your connection -^^^^^^^^^^^^^^^^^^^^ - -Use the following command to test the basic functionality. - -.. code-block:: bash - - $ openstack flavor list + pip_install.rst + source_install.rst \ No newline at end of file diff --git a/doc/source/install/pip_install.rst b/doc/source/install/pip_install.rst new file mode 100644 index 000000000..1645cf23a --- /dev/null +++ b/doc/source/install/pip_install.rst @@ -0,0 +1,175 @@ +Installation with PiP Installer +=============================== + +All three packages are written in Python and stored as Python packages in the +PyPi repository. The following section describes the installation of +``OpenStackSDK``, ``otcextensions`` and ``OpenStackClient``. Please remember, +it is not the latest development state. For this purpose the latest sources +needs to be installed. + +PiP Installation in User Space +------------------------------ + +Ubuntu or Debian +^^^^^^^^^^^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, and package manager pip are required: + +.. code-block:: bash + + $ sudo apt update + $ sudo apt install gcc python3 python3-dev python3-pip libssl-dev + +Now, install all libraries and programs at once with the Python package +manager pip. The --user flag provides user wide installation instead of a +global installation. + +.. code-block:: bash + + $ pip3 install otcextensions python-openstackclient --user + + +CentOS +^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, and package manager pip are required. If you want to +use python3 which is recommended, you need to install the epel +repository, first: + +.. code-block:: bash + + $ sudo yum update + $ sudo yum install epel-release + $ sudo yum install gcc python36 python36-devel python36-pip openssl-devel + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + $ pip3 install otcextensions python-openstackclient --user + +Fedora +^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, and package manager pip are required: + + +.. code-block:: bash + + $ sudo dnf upgrade + $ sudo dnf install gcc python3 python3-devel python3-pip openssl-devel + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + $ pip3 install otcextensions python-openstackclient --user + +PiP Installation within a Virtual Environment +--------------------------------------------- + +A virtual environment seperates your installed packages from other +libraries and should be used as well. + +Ubuntu or Debian +^^^^^^^^^^^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, package manager, and virtual environment +are required: + +.. code-block:: bash + + $ sudo apt update + $ sudo apt install gcc python3 python3-dev python3-pip python3-venv libssl-dev + +A virtual environment seperates your installed packages from other libraries +and should be used as well. You can name the virtual environment on your own +desires, in our example it is: "venv". The second command will switch +on "venv": + +.. code-block:: bash + + $ python3 -m venv venv + $ source venv/bin/activate + (venv) $ + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + $ pip install otcextensions openstackclient + + +CentOS +^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, package manager, and virtual environment are +required. If you want to use python3 which is recommended, you need to +install the epel repository, first: + + +.. code-block:: bash + + $ sudo yum update + $ sudo yum install epel-release + +No the Python packages are needed: + +.. code-block:: bash + + $ sudo yum update + $ sudo yum install gcc python36 python36-devel python-pip \ + python-virtualenv openssl-devel + +A virtual environment seperates your installed packages from other libraries +and should be used as well. You can name the virtual environment on your own +desires, in our example it is: "venv". The second command will switch +on "venv": + +.. code-block:: bash + + $ python3 -m venv venv + $ source venv/bin/activate + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + $ pip install otcextensions openstackclient + +Fedora (under review) +^^^^^^^^^^^^^^^^^^^^^ + +For the installation, following packages are required: a C compiler, +Python3 with developer libraries, package manager, and a virtual +environment are required: + +.. code-block:: bash + + $ sudo dnf upgrade + $ sudo dnf install gcc python3 python3-devel python3-pip \ + python3-virtualenv openssl-devel + +The virtual environment will be created and activated. You can name the +virtual environment on your own desires, in our example it is "venv": + +.. code-block:: bash + + $ python3 -m venv venv + $ source venv/bin/activate + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + (venv) $ pip install otcextensions openstackclient \ No newline at end of file diff --git a/doc/source/install/source_install.rst b/doc/source/install/source_install.rst new file mode 100644 index 000000000..7ecaa15af --- /dev/null +++ b/doc/source/install/source_install.rst @@ -0,0 +1,40 @@ +Installation from GitHub sources +================================ + +The latest state of the packages can be installed with the following source installation approach. + +Cloning the Github repository: + +.. code-block:: bash + + $ git clone https://github.com/OpenTelekomCloud/python-otcextensions.git + +A virtual environment seperates your installed packages from other libraries +and should be used as well. You can name the virtual environment on your own +desires, in our example it is: "venv". The second command will switch +on "venv": + +.. code-block:: bash + + $ python3 -m venv venv + $ source venv/bin/activate + (venv) $ + +Switch into the new folder which is created by cloning the repository and +install install the project dependencies into the virtual environment: + +.. code-block:: bash + + (venv) $ cd ./python-otcextensions + +Register the CLI plugin using: + +.. code-block:: bash + + (venv) ~/python-otcextensions$ python setup.py install + +Install Openstack-Client binary from pip-Repository: + +.. code-block:: bash + + (venv) ~/python-otcextensions$ pip install openstackclient \ No newline at end of file From 0846a03bb7b9003d33c8653efdca436288a37dc1 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 6 Mar 2020 11:49:48 +0000 Subject: [PATCH 07/42] reordering section Installation and OpenStack CLI --- doc/source/cli/anti_ddos.rst | 5 +-- doc/source/cli/auto_scaling.rst | 5 +-- doc/source/cli/cce_v2.rst | 5 +-- doc/source/cli/cts.rst | 5 +-- doc/source/cli/dcs.rst | 5 +-- doc/source/cli/deh.rst | 5 +-- doc/source/cli/dms.rst | 5 +-- doc/source/cli/dns.rst | 5 +-- doc/source/cli/index.rst | 2 +- doc/source/cli/kms.rst | 5 +-- doc/source/cli/load_balancer.rst | 5 +-- doc/source/cli/obs.rst | 5 +-- doc/source/cli/rds.rst | 5 +-- doc/source/cli/volume_backup.rst | 5 +-- doc/source/index.rst | 15 ++----- doc/source/install/configuration.rst | 4 +- doc/source/install/index.rst | 15 +++---- doc/source/sdk/architecture.rst | 18 ++++++++ doc/source/sdk/getting_started.rst | 64 ++++++++++++++++++++++++++++ doc/source/sdk/index.rst | 12 ++++++ doc/source/user/index.rst | 46 ++++++++++---------- 21 files changed, 156 insertions(+), 85 deletions(-) create mode 100644 doc/source/sdk/architecture.rst create mode 100644 doc/source/sdk/getting_started.rst create mode 100644 doc/source/sdk/index.rst diff --git a/doc/source/cli/anti_ddos.rst b/doc/source/cli/anti_ddos.rst index 308ba8123..de663e60c 100644 --- a/doc/source/cli/anti_ddos.rst +++ b/doc/source/cli/anti_ddos.rst @@ -1,6 +1,5 @@ -================================================= -Anti DDoS Service (Anti_DDoS) command-line client -================================================= +Anti DDoS Service (Anti_DDoS) +============================= The Anti_DDoS client is the command-line interface (CLI) for the Anti DDoS Service (Anti_DDoS) API and its extensions. diff --git a/doc/source/cli/auto_scaling.rst b/doc/source/cli/auto_scaling.rst index e67398d01..1c75844ab 100644 --- a/doc/source/cli/auto_scaling.rst +++ b/doc/source/cli/auto_scaling.rst @@ -1,6 +1,5 @@ -============================================ -AutoScaling service (AS) command-line client -============================================ +AutoScaling service (AS) +======================== The AS client is the command-line interface (CLI) for the AutoScaling service (AS) API and its extensions. diff --git a/doc/source/cli/cce_v2.rst b/doc/source/cli/cce_v2.rst index b0ab6a044..17e17c4cc 100644 --- a/doc/source/cli/cce_v2.rst +++ b/doc/source/cli/cce_v2.rst @@ -1,6 +1,5 @@ -================================================ -Cloud Container Engine (CCE) command-line client -================================================ +Cloud Container Engine (CCE) +============================ The CCE client is the command-line interface (CLI) for the Cloud Container Engine (CCE) API and its extensions for the CCE v2. diff --git a/doc/source/cli/cts.rst b/doc/source/cli/cts.rst index 7a1132218..fa5bcb3c9 100644 --- a/doc/source/cli/cts.rst +++ b/doc/source/cli/cts.rst @@ -1,6 +1,5 @@ -============================================= -Cloud Trace Service (CTS) command-line client -============================================= +Cloud Trace Service (CTS) +========================= The CTS client is the command-line interface (CLI) for the Cloud Trace Service (CTS) API and its extensions. diff --git a/doc/source/cli/dcs.rst b/doc/source/cli/dcs.rst index 516e78ad2..6c9f3edd5 100644 --- a/doc/source/cli/dcs.rst +++ b/doc/source/cli/dcs.rst @@ -1,6 +1,5 @@ -=================================================== -Distributed Cache Service (DCS) command-line client -=================================================== +Distributed Cache Service (DCS) +=============================== The DCS client is the command-line interface (CLI) for the Distributed Cache Service (DMS) API and its extensions. diff --git a/doc/source/cli/deh.rst b/doc/source/cli/deh.rst index a19e5b3b1..5975b41f4 100644 --- a/doc/source/cli/deh.rst +++ b/doc/source/cli/deh.rst @@ -1,6 +1,5 @@ -================================================ -Dedicated Host Service (DeH) command-line client -================================================ +Dedicated Host Service (DeH) +============================ The DeH client is the command-line interface (CLI) for the Dedicated Host Service (DeH) API and its extensions. diff --git a/doc/source/cli/dms.rst b/doc/source/cli/dms.rst index f51d36712..ce3370d93 100644 --- a/doc/source/cli/dms.rst +++ b/doc/source/cli/dms.rst @@ -1,6 +1,5 @@ -===================================================== -Distributed Message Service (DMS) command-line client -===================================================== +Distributed Message Service (DMS) +================================= The DMS client is the command-line interface (CLI) for the Distributed Message Service (DMS) API and its extensions. diff --git a/doc/source/cli/dns.rst b/doc/source/cli/dns.rst index b2e58c38f..e8db53d8d 100644 --- a/doc/source/cli/dns.rst +++ b/doc/source/cli/dns.rst @@ -1,6 +1,5 @@ -============================================= -Domain Name Service (DNS) command-line client -============================================= +Domain Name Service (DNS) +========================= The DNS client is the command-line interface (CLI) for the Domain Name Service (DNS) API and its extensions. diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index 524564ba6..e4b84f9c3 100644 --- a/doc/source/cli/index.rst +++ b/doc/source/cli/index.rst @@ -2,7 +2,7 @@ OpenStackClient CLI Usage ========================= .. toctree:: - :maxdepth: 2 + :maxdepth: 1 anti_ddos.rst auto_scaling.rst diff --git a/doc/source/cli/kms.rst b/doc/source/cli/kms.rst index 758421746..094bb1be3 100644 --- a/doc/source/cli/kms.rst +++ b/doc/source/cli/kms.rst @@ -1,6 +1,5 @@ -================================================ -Key Management Service (KMS) command-line client -================================================ +Key Management Service (KMS) +============================ The KMS client is the command-line interface (CLI) for the Key Management service (KMS) API and its extensions. diff --git a/doc/source/cli/load_balancer.rst b/doc/source/cli/load_balancer.rst index 5f37c93db..623caca06 100644 --- a/doc/source/cli/load_balancer.rst +++ b/doc/source/cli/load_balancer.rst @@ -1,6 +1,5 @@ -======================================== -LoadBalancer service command-line client -======================================== +Elastic LoadBalancer (ELB) +========================== The load_balancer client is the command-line interface (CLI) for the native Neutron/Octavia LoadBalancer service (load_balancer) API. diff --git a/doc/source/cli/obs.rst b/doc/source/cli/obs.rst index fae6f4bf4..4a03069cc 100644 --- a/doc/source/cli/obs.rst +++ b/doc/source/cli/obs.rst @@ -1,6 +1,5 @@ -================================================ -Object Storage service (obs) command-line client -================================================ +Object Storage service (obs) +============================ The OBS client is the command-line interface (CLI) for the ObjectBlockStorage service (OBS) API and its extensions. diff --git a/doc/source/cli/rds.rst b/doc/source/cli/rds.rst index afa7e95cb..229a41495 100644 --- a/doc/source/cli/rds.rst +++ b/doc/source/cli/rds.rst @@ -1,6 +1,5 @@ -========================================== -Database service (rds) command-line client -========================================== +Database service (rds) +====================== The RDS client is the command-line interface (CLI) for the Database service (RDS) API and its extensions. diff --git a/doc/source/cli/volume_backup.rst b/doc/source/cli/volume_backup.rst index c3243c8bd..fb2ddd4e5 100644 --- a/doc/source/cli/volume_backup.rst +++ b/doc/source/cli/volume_backup.rst @@ -1,6 +1,5 @@ -=============================================== -Volume Backup Service (VBS) command-line client -=============================================== +Volume Backup Service (VBS) +=========================== The VBS client is the command-line interface (CLI) for the Volume Backup service (vbs) API and its extensions. diff --git a/doc/source/index.rst b/doc/source/index.rst index d26578199..ed8142cef 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -19,29 +19,20 @@ cases. Additionally some auxiliary documentation is available: .. toctree:: :includehidden: - :numbered: + :numbered: 1 :maxdepth: 1 install/index install/configuration cli/index - user/index + sdk/index contributor/index history glossary releasenotes coverage issues - -1 Installation -2 CLI Usage -3 Package Reference -4 Contributing -5 History -6 Glossary of Terms -7 Release Notes -8 Service Coverage -9 Potential Issues + user/index Installation and Configuration diff --git a/doc/source/install/configuration.rst b/doc/source/install/configuration.rst index c9e5b1b01..bbf6326fa 100644 --- a/doc/source/install/configuration.rst +++ b/doc/source/install/configuration.rst @@ -1,5 +1,5 @@ -Configuration for the Cloud Connection -====================================== +Configuration +============= You can connect to the Open Telekom Cloud and OpenStack clouds in general using two approaches. The first one uses a credential file called diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index fce37b0ad..6b7f1e59b 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -1,6 +1,12 @@ Installation ============ +.. toctree:: + :maxdepth: 3 + + pip_install.rst + source_install.rst + There are several ways to install OTC Extensions to enhance the native OpenStack Client and to extend the OpenStack SDK to cover the additional Open Telekom Cloud services providing a larger @@ -31,12 +37,3 @@ OTC Extensions into a CLI tool. **OTC Extensions:** An addition to OpenStack SDK with enhanced functionality that is specific for the Open Telekom Cloud. This is the package you are currently looking at. - -Content -------- - -.. toctree:: - :maxdepth: 3 - - pip_install.rst - source_install.rst \ No newline at end of file diff --git a/doc/source/sdk/architecture.rst b/doc/source/sdk/architecture.rst new file mode 100644 index 000000000..a4040e8ad --- /dev/null +++ b/doc/source/sdk/architecture.rst @@ -0,0 +1,18 @@ +Architecture Overview and Important Terms +========================================= + +The OTC Extensions contain an abstraction interface layer. Clouds can +do many things, but there are probably only about 10 of them that most +people care about with any regularity. + +If you want to do complicated things, the per-service oriented +portions of the SDK are for you. + +However, if what you want is to be able to write an application that +talks to clouds no matter what crazy choices the deployer has made in +an attempt to be more hipster than their self-entitled narcissist +peers, then the Cloud Abstraction layer is for you. + +Please note that OTC Extensions provides an extension to the +OpenStackSDK. Please refer to it's documentation for the details + \ No newline at end of file diff --git a/doc/source/sdk/getting_started.rst b/doc/source/sdk/getting_started.rst new file mode 100644 index 000000000..b5da59ae1 --- /dev/null +++ b/doc/source/sdk/getting_started.rst @@ -0,0 +1,64 @@ +Getting Started +=============== + +Connect to the cloud +==================== + +In order to work with an OpenStack cloud you first need to create a +:class:`~openstack.connection.Connection` using your credentials. A +:class:`~openstack.connection.Connection` can be created in three +ways, using the class itself, :ref:`config-clouds-yaml`, or +:ref:`config-environment-variables`. It is recommended use +:ref:`config-clouds-yaml` as the same config can be used across tools +and languages. Examples are the OpenStack Client, the Gophercloud +library for golang, and Terraform that is based on that +library. Please be also aware that environment variables carrying +credentials can be a security risk. + +Create Connection +----------------- + +To create a :class:`~openstack.connection.Connection` instance, use the +:func:`~openstack.connect` factory function. + +As a next step inject the OTC Extensions into the retrieved connection + +.. code-block:: python + + # An 'otc' is a cloud connection with name 'otc' configured in the clouds.yaml + conn = openstack.connect(cloud='otc') + + # Register OTC Extensions + sdk.register_otc_extensions(conn) + +See a full example at `connect_otc.py `_ + +.. note:: To enable logging, see the ``_ user guide. + +Verify Installation +------------------- + +You need to have the OpenStack SDK in package `openstacksdk` installed +to work with the OTC Extensions, which are packaged in +`otcextensions`. Thanks to a plugin mechanism, no additional +configuration is needed to use the extension. To verify you are up and +running write a file `demo.py`: + +.. code-block: python + + import openstack as mycloud + + conn = mycloud.connect("otc") + conn.jjjjj.flavors() + +Make sure that you configured your credentials as describe in the +`configuration` section. Run this script with + +.. code-block: bash + $ python demo.py + +It should XXXXXXXX list your XXXXXXXX. + + +with this Python script and run it with +`python demo.py`. \ No newline at end of file diff --git a/doc/source/sdk/index.rst b/doc/source/sdk/index.rst new file mode 100644 index 000000000..f642bb03d --- /dev/null +++ b/doc/source/sdk/index.rst @@ -0,0 +1,12 @@ +OpenStack SDK Usage +=================== + +.. toctree:: + :maxdepth: 1 + + architecture + getting_started + +The OTC Extensions contain an abstraction interface layer. Clouds can +do many things, but there are probably only about 10 of them that most +people care about with any regularity. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 223f6d000..bfcb35638 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,6 +1,30 @@ Getting started with the OTC Extensions ======================================= +.. toctree:: + :maxdepth: 1 + + Plain-simple connect to OTC + Configuration + Connect to an OpenStack Cloud Using a Config File + Using Cloud Abstration Layer + Logging + Microversions + Block Storage + Compute + Identity + Image + Key Manager + Message + Network + Object Store + Orchestration + RDS + OBS + AutoScaling + Volume Backup + Dedicated Host + The OTC Extensions contain an abstraction interface layer. Clouds can do many things, but there are probably only about 10 of them that most people care about with any regularity. @@ -55,29 +79,7 @@ These guides walk you through how to make use of the libraries we provide to work with each OpenStack service. If you're looking for a cookbook approach, this is where you'll want to begin. -.. toctree:: - :maxdepth: 1 - Plain-simple connect to OTC - Configuration - Connect to an OpenStack Cloud Using a Config File - Using Cloud Abstration Layer - Logging - Microversions - Block Storage - Compute - Identity - Image - Key Manager - Message - Network - Object Store - Orchestration - RDS - OBS - AutoScaling - Volume Backup - Dedicated Host API Documentation ----------------- From 465a5c82edd46bd9fce30bda9d43b54d732d0ad4 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 6 Mar 2020 13:19:13 +0000 Subject: [PATCH 08/42] reordering SDK guides, service proxies and other stuff --- doc/source/sdk/examples | 1 + doc/source/sdk/getting_started.rst | 6 +- doc/source/sdk/guides/deh.rst | 68 ++++ doc/source/sdk/guides/index.rst | 15 + doc/source/sdk/guides/logging.rst | 114 ++++++ doc/source/sdk/index.rst | 14 + .../{user => sdk}/proxies/anti_ddos.rst | 0 .../{user => sdk}/proxies/auto_scaling.rst | 0 doc/source/{user => sdk}/proxies/cce_v1.rst | 0 doc/source/{user => sdk}/proxies/cce_v3.rst | 0 doc/source/{user => sdk}/proxies/cts.rst | 0 doc/source/{user => sdk}/proxies/dcs.rst | 0 doc/source/{user => sdk}/proxies/deh.rst | 0 doc/source/{user => sdk}/proxies/dms.rst | 0 doc/source/{user => sdk}/proxies/dns.rst | 0 doc/source/sdk/proxies/index.rst | 53 +++ doc/source/{user => sdk}/proxies/kms.rst | 0 doc/source/{user => sdk}/proxies/obs.rst | 0 doc/source/{user => sdk}/proxies/rds_v1.rst | 0 doc/source/{user => sdk}/proxies/rds_v3.rst | 0 .../{user => sdk}/proxies/volume_backup.rst | 0 doc/source/user/guides/logging.rst | 2 - doc/source/user/index.rst | 373 +++++++----------- 23 files changed, 411 insertions(+), 235 deletions(-) create mode 120000 doc/source/sdk/examples create mode 100644 doc/source/sdk/guides/deh.rst create mode 100644 doc/source/sdk/guides/index.rst create mode 100644 doc/source/sdk/guides/logging.rst rename doc/source/{user => sdk}/proxies/anti_ddos.rst (100%) rename doc/source/{user => sdk}/proxies/auto_scaling.rst (100%) rename doc/source/{user => sdk}/proxies/cce_v1.rst (100%) rename doc/source/{user => sdk}/proxies/cce_v3.rst (100%) rename doc/source/{user => sdk}/proxies/cts.rst (100%) rename doc/source/{user => sdk}/proxies/dcs.rst (100%) rename doc/source/{user => sdk}/proxies/deh.rst (100%) rename doc/source/{user => sdk}/proxies/dms.rst (100%) rename doc/source/{user => sdk}/proxies/dns.rst (100%) create mode 100644 doc/source/sdk/proxies/index.rst rename doc/source/{user => sdk}/proxies/kms.rst (100%) rename doc/source/{user => sdk}/proxies/obs.rst (100%) rename doc/source/{user => sdk}/proxies/rds_v1.rst (100%) rename doc/source/{user => sdk}/proxies/rds_v3.rst (100%) rename doc/source/{user => sdk}/proxies/volume_backup.rst (100%) diff --git a/doc/source/sdk/examples b/doc/source/sdk/examples new file mode 120000 index 000000000..d4cb9b9c8 --- /dev/null +++ b/doc/source/sdk/examples @@ -0,0 +1 @@ +../../../examples/ \ No newline at end of file diff --git a/doc/source/sdk/getting_started.rst b/doc/source/sdk/getting_started.rst index b5da59ae1..bebdab984 100644 --- a/doc/source/sdk/getting_started.rst +++ b/doc/source/sdk/getting_started.rst @@ -2,7 +2,7 @@ Getting Started =============== Connect to the cloud -==================== +-------------------- In order to work with an OpenStack cloud you first need to create a :class:`~openstack.connection.Connection` using your credentials. A @@ -16,7 +16,7 @@ library. Please be also aware that environment variables carrying credentials can be a security risk. Create Connection ------------------ +^^^^^^^^^^^^^^^^^ To create a :class:`~openstack.connection.Connection` instance, use the :func:`~openstack.connect` factory function. @@ -36,7 +36,7 @@ See a full example at `connect_otc.py `_ .. note:: To enable logging, see the ``_ user guide. Verify Installation -------------------- +^^^^^^^^^^^^^^^^^^^ You need to have the OpenStack SDK in package `openstacksdk` installed to work with the OTC Extensions, which are packaged in diff --git a/doc/source/sdk/guides/deh.rst b/doc/source/sdk/guides/deh.rst new file mode 100644 index 000000000..8e0f49bfd --- /dev/null +++ b/doc/source/sdk/guides/deh.rst @@ -0,0 +1,68 @@ +Dedicated Hosts (DeH) +===================== + +.. contents:: Table of Contents + :local: + +The primary resource of the DeH service is the **host**. + +CRUD operations +~~~~~~~~~~~~~~~ + +List Hosts +---------- + +A **host** is a dedicated host, where virtual machines would be running. + +.. literalinclude:: ../examples/deh/list.py + :pyobject: list_hosts + +Full example: `deh host list`_ + +List Hosts Types +---------------- + +In order to allocate a host, it's type need to be chosen first. Types might +differ per availability zone, therefore it is required to specify in which +AZ to look for types + +.. literalinclude:: ../examples/deh/list_types.py + :pyobject: list_host_types + +Full example: `deh host list type`_ + +List Host servers +----------------- + +Each DeH Host is intended to run virtual instances. Only querying list of +servers is supported + +.. literalinclude:: ../examples/deh/list_servers.py + :pyobject: list_host_servers + +Full example: `deh host list server`_ + +Provisioning operations +~~~~~~~~~~~~~~~~~~~~~~~ + +Provisioning actions are the main way to manipulate the hosts. + +Allocating a DeH Host Instance +------------------------------ + +A host can be allocated with a following snip. + +.. literalinclude:: ../examples/deh/create.py + :pyobject: create_host + +Allocating a DeH Host supports setting `quantity` parameter to allocate +multiple hosts in a one call. Due to that the IDs of allocated hosts are being +returned as part of the "virtual" resource in a `dedicated_host_ids` attribute + +Full example: `deh host create`_ + + +.. _deh host list: https://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/list.py +.. _deh host list type: https://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/list_types.py +.. _deh host create: https://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/create.py +.. _deh host list server: https://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/list_servers.py diff --git a/doc/source/sdk/guides/index.rst b/doc/source/sdk/guides/index.rst new file mode 100644 index 000000000..49c1f1b74 --- /dev/null +++ b/doc/source/sdk/guides/index.rst @@ -0,0 +1,15 @@ +Guides for SDK +============== + +.. toctree:: + :maxdepth: 1 + + deh.rst + logging.rst + +.. _user_guides: + +User Guides +----------- + +SOME TEXT \ No newline at end of file diff --git a/doc/source/sdk/guides/logging.rst b/doc/source/sdk/guides/logging.rst new file mode 100644 index 000000000..6eb4da4a5 --- /dev/null +++ b/doc/source/sdk/guides/logging.rst @@ -0,0 +1,114 @@ +======= +Logging +======= + +.. note:: TODO(shade) This document is written from a shade POV. It needs to + be combined with the existing logging guide, but also the logging + systems need to be rationalized. + +`openstacksdk` uses `Python Logging`_. As `openstacksdk` is a library, it does +not configure logging handlers automatically, expecting instead for that to be +the purview of the consuming application. + +Simple Usage +------------ + +For consumers who just want to get a basic logging setup without thinking +about it too deeply, there is a helper method. If used, it should be called +before any other openstacksdk functionality. + +.. autofunction:: openstack.enable_logging + +.. code-block:: python + + import openstack + openstack.enable_logging() + +The ``stream`` parameter controls the stream where log message are written to. +It defaults to `sys.stdout` which will result in log messages being written +to STDOUT. It can be set to another output stream, or to ``None`` to disable +logging to the console. + +The ``path`` parameter sets up logging to log to a file. By default, if +``path`` is given and ``stream`` is not, logging will only go to ``path``. + +You can combine the ``path`` and ``stream`` parameters to log to both places +simultaneously. + +To log messages to a file called ``openstack.log`` and the console on +``stdout``: + +.. code-block:: python + + import sys + import openstack + + openstack.enable_logging( + debug=True, path='openstack.log', stream=sys.stdout) + + +`openstack.enable_logging` also sets up a few other loggers and +squelches some warnings or log messages that are otherwise uninteresting or +unactionable by an openstacksdk user. + +Advanced Usage +-------------- + +`openstacksdk` logs to a set of different named loggers. + +Most of the logging is set up to log to the root ``openstack`` logger. +There are additional sub-loggers that are used at times, primarily so that a +user can decide to turn on or off a specific type of logging. They are listed +below. + +openstack.config + Issues pertaining to configuration are logged to the ``openstack.config`` + logger. + +openstack.task_manager + `openstacksdk` uses a Task Manager to perform remote calls. The + ``openstack.task_manager`` logger emits messages at the start and end + of each Task announcing what it is going to run and then what it ran and + how long it took. Logging ``openstack.task_manager`` is a good way to + get a trace of external actions `openstacksdk` is taking without full + `HTTP Tracing`_. + +openstack.iterate_timeout + When `openstacksdk` needs to poll a resource, it does so in a loop that waits + between iterations and ultimately times out. The + ``openstack.iterate_timeout`` logger emits messages for each iteration + indicating it is waiting and for how long. These can be useful to see for + long running tasks so that one can know things are not stuck, but can also + be noisy. + +openstack.fnmatch + `openstacksdk` will try to use `fnmatch`_ on given `name_or_id` arguments. + It's a best effort attempt, so pattern misses are logged to + ``openstack.fnmatch``. A user may not be intending to use an fnmatch + pattern - such as if they are trying to find an image named + ``Fedora 24 [official]``, so these messages are logged separately. + +.. _fnmatch: https://pymotw.com/2/fnmatch/ + +HTTP Tracing +------------ + +HTTP Interactions are handled by `keystoneauth`_. If you want to enable HTTP +tracing while using openstacksdk and are not using `openstack.enable_logging`, +set the log level of the ``keystoneauth`` logger to ``DEBUG``. + +For more information see https://docs.openstack.org/keystoneauth/latest/using-sessions.html#logging + +.. _keystoneauth: https://docs.openstack.org/keystoneauth/latest/ + +Python Logging +-------------- + +Python logging is a standard feature of Python and is documented fully in the +Python Documentation, which varies by version of Python. + +For more information on Python Logging for Python v2, see +https://docs.python.org/2/library/logging.html. + +For more information on Python Logging for Python v3, see +https://docs.python.org/3/library/logging.html. diff --git a/doc/source/sdk/index.rst b/doc/source/sdk/index.rst index f642bb03d..05aac3b25 100644 --- a/doc/source/sdk/index.rst +++ b/doc/source/sdk/index.rst @@ -6,7 +6,21 @@ OpenStack SDK Usage architecture getting_started + guides/index + proxies/index The OTC Extensions contain an abstraction interface layer. Clouds can do many things, but there are probably only about 10 of them that most people care about with any regularity. + +If you want to do complicated things, the per-service oriented +portions of the SDK are for you. + +However, if what you want is to be able to write an application that +talks to clouds no matter what crazy choices the deployer has made in +an attempt to be more hipster than their self-entitled narcissist +peers, then the Cloud Abstraction layer is for you. + +Please note that OTC Extensions provides an extension to the +OpenStackSDK. Please refer to it's documentation for the details + diff --git a/doc/source/user/proxies/anti_ddos.rst b/doc/source/sdk/proxies/anti_ddos.rst similarity index 100% rename from doc/source/user/proxies/anti_ddos.rst rename to doc/source/sdk/proxies/anti_ddos.rst diff --git a/doc/source/user/proxies/auto_scaling.rst b/doc/source/sdk/proxies/auto_scaling.rst similarity index 100% rename from doc/source/user/proxies/auto_scaling.rst rename to doc/source/sdk/proxies/auto_scaling.rst diff --git a/doc/source/user/proxies/cce_v1.rst b/doc/source/sdk/proxies/cce_v1.rst similarity index 100% rename from doc/source/user/proxies/cce_v1.rst rename to doc/source/sdk/proxies/cce_v1.rst diff --git a/doc/source/user/proxies/cce_v3.rst b/doc/source/sdk/proxies/cce_v3.rst similarity index 100% rename from doc/source/user/proxies/cce_v3.rst rename to doc/source/sdk/proxies/cce_v3.rst diff --git a/doc/source/user/proxies/cts.rst b/doc/source/sdk/proxies/cts.rst similarity index 100% rename from doc/source/user/proxies/cts.rst rename to doc/source/sdk/proxies/cts.rst diff --git a/doc/source/user/proxies/dcs.rst b/doc/source/sdk/proxies/dcs.rst similarity index 100% rename from doc/source/user/proxies/dcs.rst rename to doc/source/sdk/proxies/dcs.rst diff --git a/doc/source/user/proxies/deh.rst b/doc/source/sdk/proxies/deh.rst similarity index 100% rename from doc/source/user/proxies/deh.rst rename to doc/source/sdk/proxies/deh.rst diff --git a/doc/source/user/proxies/dms.rst b/doc/source/sdk/proxies/dms.rst similarity index 100% rename from doc/source/user/proxies/dms.rst rename to doc/source/sdk/proxies/dms.rst diff --git a/doc/source/user/proxies/dns.rst b/doc/source/sdk/proxies/dns.rst similarity index 100% rename from doc/source/user/proxies/dns.rst rename to doc/source/sdk/proxies/dns.rst diff --git a/doc/source/sdk/proxies/index.rst b/doc/source/sdk/proxies/index.rst new file mode 100644 index 000000000..449a484a7 --- /dev/null +++ b/doc/source/sdk/proxies/index.rst @@ -0,0 +1,53 @@ +Service Proxies +=============== + +.. toctree:: + :maxdepth: 1 + + Anti DDoS Service + AutoScaling Service + Cloud Container Engine v1 + Cloud Container Engine v2 + Cloud Trace Service + Distributed Cache Service + Dedicated Host Service + Distributed Message Service + DNS Service + Key Management Service + Object Block Storage + Volume Backup Service + Relational Database Service RDS V1 + Relational Database Service RDS V3 + +.. _service-proxies: + +Service Proxies +--------------- + +The following service proxies exist on the +:class:`~openstack.connection.Connection`. The service proxies are all always +present on the :class:`~openstack.connection.Connection` object, but the +combination of your ``CloudRegion`` and the catalog of the cloud in question +control which services can be used. + +Links to Native OpenStack Service Proxies +----------------------------------------- + +.. toctree:: + :maxdepth: 1 + + Block Storage + Compute + Database + Identity v2 + Identity v3 + Image v1 + Image v2 + Key Manager + Load Balancer + Message v2 + Network + Object Store + Orchestration + Workflow + diff --git a/doc/source/user/proxies/kms.rst b/doc/source/sdk/proxies/kms.rst similarity index 100% rename from doc/source/user/proxies/kms.rst rename to doc/source/sdk/proxies/kms.rst diff --git a/doc/source/user/proxies/obs.rst b/doc/source/sdk/proxies/obs.rst similarity index 100% rename from doc/source/user/proxies/obs.rst rename to doc/source/sdk/proxies/obs.rst diff --git a/doc/source/user/proxies/rds_v1.rst b/doc/source/sdk/proxies/rds_v1.rst similarity index 100% rename from doc/source/user/proxies/rds_v1.rst rename to doc/source/sdk/proxies/rds_v1.rst diff --git a/doc/source/user/proxies/rds_v3.rst b/doc/source/sdk/proxies/rds_v3.rst similarity index 100% rename from doc/source/user/proxies/rds_v3.rst rename to doc/source/sdk/proxies/rds_v3.rst diff --git a/doc/source/user/proxies/volume_backup.rst b/doc/source/sdk/proxies/volume_backup.rst similarity index 100% rename from doc/source/user/proxies/volume_backup.rst rename to doc/source/sdk/proxies/volume_backup.rst diff --git a/doc/source/user/guides/logging.rst b/doc/source/user/guides/logging.rst index 6eb4da4a5..7a41b950d 100644 --- a/doc/source/user/guides/logging.rst +++ b/doc/source/user/guides/logging.rst @@ -17,8 +17,6 @@ For consumers who just want to get a basic logging setup without thinking about it too deeply, there is a helper method. If used, it should be called before any other openstacksdk functionality. -.. autofunction:: openstack.enable_logging - .. code-block:: python import openstack diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index bfcb35638..d8c15fb0a 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,230 +1,143 @@ -Getting started with the OTC Extensions -======================================= - -.. toctree:: - :maxdepth: 1 - - Plain-simple connect to OTC - Configuration - Connect to an OpenStack Cloud Using a Config File - Using Cloud Abstration Layer - Logging - Microversions - Block Storage - Compute - Identity - Image - Key Manager - Message - Network - Object Store - Orchestration - RDS - OBS - AutoScaling - Volume Backup - Dedicated Host - -The OTC Extensions contain an abstraction interface layer. Clouds can -do many things, but there are probably only about 10 of them that most -people care about with any regularity. - -If you want to do complicated things, the per-service oriented -portions of the SDK are for you. - -However, if what you want is to be able to write an application that -talks to clouds no matter what crazy choices the deployer has made in -an attempt to be more hipster than their self-entitled narcissist -peers, then the Cloud Abstraction layer is for you. - -Please note that OTC Extensions provides an extension to the -OpenStackSDK. Please refer to it's documentation for the details - - - -Verify Installation -------------------- - -You need to have the OpenStack SDK in package `openstacksdk` installed -to work with the OTC Extensions, which are packaged in -`otcextensions`. Thanks to a plugin mechanism, no additional -configuration is needed to use the extension. To verify you are up and -running write a file `demo.py`: - -.. code-block: python - - import openstack as mycloud - - conn = mycloud.connect("otc") - conn.jjjjj.flavors() - -Make sure that you configured your credentials as describe in the -`configuration` section. Run this script with - -.. code-block: bash - $ python demo.py - -It should XXXXXXXX list your XXXXXXXX. - - -with this Python script and run it with -`python demo.py`. - -.. _user_guides: - -User Guides ------------ - -These guides walk you through how to make use of the libraries we provide -to work with each OpenStack service. If you're looking for a cookbook -approach, this is where you'll want to begin. - - - -API Documentation ------------------ - -OpenStackSDK documentation is available under - - -Service APIs are exposed through a two-layered approach. The classes -exposed through our `Connection Interface`_ are -the place to start if you're an application developer consuming an OpenStack -cloud. The `Resource Interface`_ is the layer upon which the -`Connection Interface`_ is built, with methods on `Service Proxies`_ accepting -and returning :class:`~openstack.resource.Resource` objects. - -The Cloud Abstraction layer has a data model. - -.. toctree:: - :maxdepth: 1 - - model - -Connection Interface -~~~~~~~~~~~~~~~~~~~~ - -A :class:`~openstack.connection.Connection` instance maintains your cloud -config, session and authentication information providing you with a set of -higher-level interfaces to work with OpenStack services. - -.. toctree:: - :maxdepth: 1 - - connection - -Once you have a :class:`~openstack.connection.Connection` instance, services -are accessed through instances of :class:`~openstack.proxy.Proxy` or -subclasses of it that exist as attributes on the -:class:`~openstack.connection.Connection`. - -.. autoclass:: openstack.proxy.Proxy - :members: - -.. _service-proxies: - -Service Proxies -~~~~~~~~~~~~~~~ - -The following service proxies exist on the -:class:`~openstack.connection.Connection`. The service proxies are all always -present on the :class:`~openstack.connection.Connection` object, but the -combination of your ``CloudRegion`` and the catalog of the cloud in question -control which services can be used. - -.. toctree:: - :maxdepth: 1 - - Block Storage - Compute - Database - Identity v2 - Identity v3 - Image v1 - Image v2 - Key Manager - Load Balancer - Message v2 - Network - Object Store - Orchestration - Workflow - Anti DDoS Service - AutoScaling Service - Cloud Container Engine v1 - Cloud Container Engine v2 - Cloud Trace Service - Distributed Cache Service - Dedicated Host Service - Distributed Message Service - DNS Service - Key Management Service - Object Block Storage - Volume Backup Service - Relational Database Service RDS V1 - Relational Database Service RDS V3 - -Resource Interface -~~~~~~~~~~~~~~~~~~ - -The *Resource* layer is a lower-level interface to -communicate with OpenStack services. While the classes exposed by the -`Service Proxies`_ build a convenience layer on top of -this, :class:`~openstack.resource.Resource` objects can be -used directly. However, the most common usage of this layer is in receiving -an object from a class in the `Connection Interface_`, modifying it, and -sending it back to the `Service Proxies`_ layer, such as to update a resource -on the server. - -The following services have exposed :class:`~openstack.resource.Resource` -classes. - -.. toctree:: - :maxdepth: 1 - - Baremetal - Block Storage - Clustering - Compute - Database - Identity - Image - Key Management - Load Balancer - Network - Orchestration - Object Store - Workflow - Anti DDoS Service - AutoScaling Service - DNS Service - Cloud Container Engine - Cloud Trace Service - Distributed Cache Service - Dedicated Host Service - Distributed Message Service - Key Management Service - Object Block Storage - RDS - -Low-Level Classes -~~~~~~~~~~~~~~~~~ - -The following classes are not commonly used by application developers, -but are used to construct applications to talk to OpenStack APIs. Typically -these parts are managed through the `Connection Interface`_, but their use -can be customized. - -.. toctree:: - :maxdepth: 1 - - resource - utils - -Presentations -============= - -.. toctree:: - :maxdepth: 1 - - multi-cloud-demo +Getting started with the OTCExtensions SDK +========================================== + +Please note that OTCExtensions provides an extension to the OpenStackSDK. +Please refer to it's documentation for the details + + + +User Guides +----------- + +These guides walk you through how to make use of the libraries we provide +to work with each OpenStack service. If you're looking for a cookbook +approach, this is where you'll want to begin. + +.. toctree:: + :maxdepth: 1 + + Plain-simple connect to OTC + Configuration + Connect to an OpenStack Cloud Using a Config File + Using Cloud Abstration Layer + Logging + Microversions + Block Storage + Compute + Identity + Image + Key Manager + Message + Network + Object Store + Orchestration + RDS + OBS + AutoScaling + Volume Backup + Dedicated Host + +API Documentation +----------------- + +OpenStackSDK documentation is available under + + +Service APIs are exposed through a two-layered approach. The classes +exposed through our `Connection Interface`_ are +the place to start if you're an application developer consuming an OpenStack +cloud. The `Resource Interface`_ is the layer upon which the +`Connection Interface`_ is built, with methods on Service Proxies accepting +and returning :class:`~openstack.resource.Resource` objects. + +The Cloud Abstraction layer has a data model. + +.. toctree:: + :maxdepth: 1 + + model + +Connection Interface +~~~~~~~~~~~~~~~~~~~~ + +A :class:`~openstack.connection.Connection` instance maintains your cloud +config, session and authentication information providing you with a set of +higher-level interfaces to work with OpenStack services. + +.. toctree:: + :maxdepth: 1 + + connection + +Once you have a :class:`~openstack.connection.Connection` instance, services +are accessed through instances of :class:`~openstack.proxy.Proxy` or +subclasses of it that exist as attributes on the +:class:`~openstack.connection.Connection`. + +.. autoclass:: openstack.proxy.Proxy + :members: + +Resource Interface +~~~~~~~~~~~~~~~~~~ + +The *Resource* layer is a lower-level interface to +communicate with OpenStack services. While the classes exposed by the +Service Proxies build a convenience layer on top of +this, :class:`~openstack.resource.Resource` objects can be +used directly. However, the most common usage of this layer is in receiving +an object from a class in the `Connection Interface_`, modifying it, and +sending it back to the Service Proxies layer, such as to update a resource +on the server. + +The following services have exposed :class:`~openstack.resource.Resource` +classes. + +.. toctree:: + :maxdepth: 1 + + Baremetal + Block Storage + Clustering + Compute + Database + Identity + Image + Key Management + Load Balancer + Network + Orchestration + Object Store + Workflow + Anti DDoS Service + AutoScaling Service + DNS Service + Cloud Container Engine + Cloud Trace Service + Distributed Cache Service + Dedicated Host Service + Distributed Message Service + Key Management Service + Object Block Storage + RDS + +Low-Level Classes +~~~~~~~~~~~~~~~~~ + +The following classes are not commonly used by application developers, +but are used to construct applications to talk to OpenStack APIs. Typically +these parts are managed through the `Connection Interface`_, but their use +can be customized. + +.. toctree:: + :maxdepth: 1 + + resource + utils + +Presentations +============= + +.. toctree:: + :maxdepth: 1 + + multi-cloud-demo From e76fbbc4dad66f30e0c0d8b798d100109d5c3603 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Tue, 10 Mar 2020 09:14:52 +0000 Subject: [PATCH 09/42] user guides reordered --- doc/source/cli/index.rst | 2 +- doc/source/sdk/guides/index.rst | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index e4b84f9c3..af93b47d5 100644 --- a/doc/source/cli/index.rst +++ b/doc/source/cli/index.rst @@ -1,4 +1,4 @@ -OpenStackClient CLI Usage +OpenStack CLI Usage ========================= .. toctree:: diff --git a/doc/source/sdk/guides/index.rst b/doc/source/sdk/guides/index.rst index 49c1f1b74..f4589ce83 100644 --- a/doc/source/sdk/guides/index.rst +++ b/doc/source/sdk/guides/index.rst @@ -12,4 +12,18 @@ Guides for SDK User Guides ----------- -SOME TEXT \ No newline at end of file +SOME TEXT + +OpenStack native User Guides +---------------------------- + + Block Storage + Compute + Identity + Image + Key Manager + Message + Microversions + Network + Object Store + Using Cloud Abstration Layer \ No newline at end of file From d35509a6dd1d15ddd44bd6fad0b5b4e0e02f66e4 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Tue, 10 Mar 2020 09:16:22 +0000 Subject: [PATCH 10/42] user guides reordered --- doc/source/sdk/guides/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/source/sdk/guides/index.rst b/doc/source/sdk/guides/index.rst index f4589ce83..1c64c39d3 100644 --- a/doc/source/sdk/guides/index.rst +++ b/doc/source/sdk/guides/index.rst @@ -17,6 +17,9 @@ SOME TEXT OpenStack native User Guides ---------------------------- +.. toctree:: + :maxdepth: 1 + Block Storage Compute Identity From 3f1426716e8e4e631307970d71edaad6d812d986 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Tue, 10 Mar 2020 12:10:22 +0000 Subject: [PATCH 11/42] restructuring done --- doc/source/{ => appendices}/glossary.rst | 0 doc/source/{ => appendices}/history.rst | 0 doc/source/appendices/index.rst | 10 + doc/source/{ => appendices}/issues.rst | 0 doc/source/{ => appendices}/releasenotes.rst | 0 doc/source/contributor/coding.rst | 3 +- doc/source/contributor/contributing.rst | 1 - doc/source/contributor/index.rst | 66 +- doc/source/index.rst | 25 +- doc/source/sdk/getting_started.rst | 6 +- doc/source/sdk/proxies/auto_scaling.rst | 2 +- doc/source/sdk/proxies/obs.rst | 2 +- doc/source/sdk/proxies/rds_v1.rst | 2 +- doc/source/sdk/proxies/rds_v3.rst | 2 +- doc/source/sdk/proxies/volume_backup.rst | 2 +- doc/source/user/config/configuration.rst | 322 ------- doc/source/user/config/index.rst | 12 - doc/source/user/config/network-config.rst | 67 -- doc/source/user/config/reference.rst | 14 - doc/source/user/config/using.rst | 58 -- doc/source/user/config/vendor-support.rst | 343 -------- doc/source/user/connection.rst | 31 - doc/source/user/examples | 1 - doc/source/user/guides/auto_scaling.rst | 4 - doc/source/user/guides/connect_otc.rst | 39 - doc/source/user/guides/deh.rst | 73 -- doc/source/user/guides/logging.rst | 112 --- doc/source/user/guides/obs.rst | 4 - doc/source/user/guides/rds.rst | 4 - doc/source/user/guides/volume_backup.rst | 4 - doc/source/user/index.rst | 143 ---- doc/source/user/model.rst | 533 ------------ doc/source/user/multi-cloud-demo.rst | 809 ------------------ doc/source/user/resource.rst | 26 - doc/source/user/resources/anti_ddos/index.rst | 9 - .../user/resources/anti_ddos/v1/config.rst | 13 - .../resources/anti_ddos/v1/floating_ip.rst | 13 - .../user/resources/anti_ddos/v1/status.rst | 58 -- .../user/resources/auto_scaling/index.rst | 12 - .../resources/auto_scaling/v1/activity.rst | 13 - .../user/resources/auto_scaling/v1/config.rst | 13 - .../user/resources/auto_scaling/v1/group.rst | 13 - .../resources/auto_scaling/v1/instance.rst | 13 - .../user/resources/auto_scaling/v1/policy.rst | 13 - .../user/resources/auto_scaling/v1/quota.rst | 22 - doc/source/user/resources/cce/index.rst | 10 - doc/source/user/resources/cce/v1/cluster.rst | 13 - .../user/resources/cce/v1/cluster_node.rst | 13 - doc/source/user/resources/cce/v3/cluster.rst | 13 - .../user/resources/cce/v3/cluster_node.rst | 13 - doc/source/user/resources/cts/index.rst | 8 - doc/source/user/resources/cts/v1/trace.rst | 13 - doc/source/user/resources/cts/v1/tracker.rst | 13 - doc/source/user/resources/dcs/index.rst | 11 - doc/source/user/resources/dcs/v1/backup.rst | 13 - doc/source/user/resources/dcs/v1/config.rst | 13 - doc/source/user/resources/dcs/v1/instance.rst | 13 - doc/source/user/resources/dcs/v1/restore.rst | 13 - .../user/resources/dcs/v1/statistic.rst | 13 - doc/source/user/resources/deh/index.rst | 9 - doc/source/user/resources/deh/v1/host.rst | 13 - .../user/resources/deh/v1/host_type.rst | 13 - doc/source/user/resources/deh/v1/server.rst | 13 - doc/source/user/resources/dms/index.rst | 11 - doc/source/user/resources/dms/v1/group.rst | 13 - .../user/resources/dms/v1/group_message.rst | 13 - doc/source/user/resources/dms/v1/message.rst | 13 - doc/source/user/resources/dms/v1/queue.rst | 13 - doc/source/user/resources/dms/v1/quota.rst | 13 - doc/source/user/resources/dns/index.rst | 10 - .../user/resources/dns/v2/floating_ip.rst | 13 - .../user/resources/dns/v2/nameserver.rst | 13 - .../user/resources/dns/v2/recordset.rst | 13 - doc/source/user/resources/dns/v2/zone.rst | 13 - doc/source/user/resources/kms/index.rst | 8 - doc/source/user/resources/kms/v1/data_key.rst | 13 - doc/source/user/resources/kms/v1/key.rst | 13 - doc/source/user/resources/obs/index.rst | 8 - .../user/resources/obs/v1/container.rst | 13 - doc/source/user/resources/obs/v1/obj.rst | 13 - doc/source/user/resources/rds/index.rst | 12 - .../user/resources/rds/v1/configuration.rst | 13 - doc/source/user/resources/rds/v1/flavor.rst | 13 - doc/source/user/resources/rds/v1/instance.rst | 13 - .../user/resources/rds/v3/configuration.rst | 13 - doc/source/user/resources/rds/v3/flavor.rst | 13 - doc/source/user/resources/rds/v3/instance.rst | 13 - doc/source/user/transition_from_profile.rst | 186 ---- doc/source/user/utils.rst | 3 - 89 files changed, 56 insertions(+), 3561 deletions(-) rename doc/source/{ => appendices}/glossary.rst (100%) rename doc/source/{ => appendices}/history.rst (100%) create mode 100644 doc/source/appendices/index.rst rename doc/source/{ => appendices}/issues.rst (100%) rename doc/source/{ => appendices}/releasenotes.rst (100%) delete mode 100644 doc/source/contributor/contributing.rst delete mode 100644 doc/source/user/config/configuration.rst delete mode 100644 doc/source/user/config/index.rst delete mode 100644 doc/source/user/config/network-config.rst delete mode 100644 doc/source/user/config/reference.rst delete mode 100644 doc/source/user/config/using.rst delete mode 100644 doc/source/user/config/vendor-support.rst delete mode 100644 doc/source/user/connection.rst delete mode 120000 doc/source/user/examples delete mode 100644 doc/source/user/guides/auto_scaling.rst delete mode 100644 doc/source/user/guides/connect_otc.rst delete mode 100644 doc/source/user/guides/deh.rst delete mode 100644 doc/source/user/guides/logging.rst delete mode 100644 doc/source/user/guides/obs.rst delete mode 100644 doc/source/user/guides/rds.rst delete mode 100644 doc/source/user/guides/volume_backup.rst delete mode 100644 doc/source/user/index.rst delete mode 100644 doc/source/user/model.rst delete mode 100644 doc/source/user/multi-cloud-demo.rst delete mode 100644 doc/source/user/resource.rst delete mode 100644 doc/source/user/resources/anti_ddos/index.rst delete mode 100644 doc/source/user/resources/anti_ddos/v1/config.rst delete mode 100644 doc/source/user/resources/anti_ddos/v1/floating_ip.rst delete mode 100644 doc/source/user/resources/anti_ddos/v1/status.rst delete mode 100644 doc/source/user/resources/auto_scaling/index.rst delete mode 100644 doc/source/user/resources/auto_scaling/v1/activity.rst delete mode 100644 doc/source/user/resources/auto_scaling/v1/config.rst delete mode 100644 doc/source/user/resources/auto_scaling/v1/group.rst delete mode 100644 doc/source/user/resources/auto_scaling/v1/instance.rst delete mode 100644 doc/source/user/resources/auto_scaling/v1/policy.rst delete mode 100644 doc/source/user/resources/auto_scaling/v1/quota.rst delete mode 100644 doc/source/user/resources/cce/index.rst delete mode 100644 doc/source/user/resources/cce/v1/cluster.rst delete mode 100644 doc/source/user/resources/cce/v1/cluster_node.rst delete mode 100644 doc/source/user/resources/cce/v3/cluster.rst delete mode 100644 doc/source/user/resources/cce/v3/cluster_node.rst delete mode 100644 doc/source/user/resources/cts/index.rst delete mode 100644 doc/source/user/resources/cts/v1/trace.rst delete mode 100644 doc/source/user/resources/cts/v1/tracker.rst delete mode 100644 doc/source/user/resources/dcs/index.rst delete mode 100644 doc/source/user/resources/dcs/v1/backup.rst delete mode 100644 doc/source/user/resources/dcs/v1/config.rst delete mode 100644 doc/source/user/resources/dcs/v1/instance.rst delete mode 100644 doc/source/user/resources/dcs/v1/restore.rst delete mode 100644 doc/source/user/resources/dcs/v1/statistic.rst delete mode 100644 doc/source/user/resources/deh/index.rst delete mode 100644 doc/source/user/resources/deh/v1/host.rst delete mode 100644 doc/source/user/resources/deh/v1/host_type.rst delete mode 100644 doc/source/user/resources/deh/v1/server.rst delete mode 100644 doc/source/user/resources/dms/index.rst delete mode 100644 doc/source/user/resources/dms/v1/group.rst delete mode 100644 doc/source/user/resources/dms/v1/group_message.rst delete mode 100644 doc/source/user/resources/dms/v1/message.rst delete mode 100644 doc/source/user/resources/dms/v1/queue.rst delete mode 100644 doc/source/user/resources/dms/v1/quota.rst delete mode 100644 doc/source/user/resources/dns/index.rst delete mode 100644 doc/source/user/resources/dns/v2/floating_ip.rst delete mode 100644 doc/source/user/resources/dns/v2/nameserver.rst delete mode 100644 doc/source/user/resources/dns/v2/recordset.rst delete mode 100644 doc/source/user/resources/dns/v2/zone.rst delete mode 100644 doc/source/user/resources/kms/index.rst delete mode 100644 doc/source/user/resources/kms/v1/data_key.rst delete mode 100644 doc/source/user/resources/kms/v1/key.rst delete mode 100644 doc/source/user/resources/obs/index.rst delete mode 100644 doc/source/user/resources/obs/v1/container.rst delete mode 100644 doc/source/user/resources/obs/v1/obj.rst delete mode 100644 doc/source/user/resources/rds/index.rst delete mode 100644 doc/source/user/resources/rds/v1/configuration.rst delete mode 100644 doc/source/user/resources/rds/v1/flavor.rst delete mode 100644 doc/source/user/resources/rds/v1/instance.rst delete mode 100644 doc/source/user/resources/rds/v3/configuration.rst delete mode 100644 doc/source/user/resources/rds/v3/flavor.rst delete mode 100644 doc/source/user/resources/rds/v3/instance.rst delete mode 100644 doc/source/user/transition_from_profile.rst delete mode 100644 doc/source/user/utils.rst diff --git a/doc/source/glossary.rst b/doc/source/appendices/glossary.rst similarity index 100% rename from doc/source/glossary.rst rename to doc/source/appendices/glossary.rst diff --git a/doc/source/history.rst b/doc/source/appendices/history.rst similarity index 100% rename from doc/source/history.rst rename to doc/source/appendices/history.rst diff --git a/doc/source/appendices/index.rst b/doc/source/appendices/index.rst new file mode 100644 index 000000000..0b54d3916 --- /dev/null +++ b/doc/source/appendices/index.rst @@ -0,0 +1,10 @@ +Appendices +========== + +.. toctree:: + :maxdepth: 1 + + releasenotes.rst + history.rst + issues.rst + glossary.rst \ No newline at end of file diff --git a/doc/source/issues.rst b/doc/source/appendices/issues.rst similarity index 100% rename from doc/source/issues.rst rename to doc/source/appendices/issues.rst diff --git a/doc/source/releasenotes.rst b/doc/source/appendices/releasenotes.rst similarity index 100% rename from doc/source/releasenotes.rst rename to doc/source/appendices/releasenotes.rst diff --git a/doc/source/contributor/coding.rst b/doc/source/contributor/coding.rst index 14ab10ff8..bf76efb5d 100644 --- a/doc/source/contributor/coding.rst +++ b/doc/source/contributor/coding.rst @@ -69,8 +69,7 @@ All objects should be normalized. It is shade's purpose in life to make OpenStack consistent for end users, and this means not trusting the clouds to return consistent objects. There should be a normalize function in `openstack/cloud/_normalize.py` that is applied to objects before returning -them to the user. See :doc:`../user/model` for further details on object model -requirements. +them to the user. Fields should not be in the normalization contract if we cannot commit to providing them to all users. diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst deleted file mode 100644 index b1cd2f37d..000000000 --- a/doc/source/contributor/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 9c48e2af3..360d515a5 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -3,29 +3,36 @@ Contributing to the OTC Extensions This section of documentation pertains to those who wish to contribute to the development of this project. If you're looking for documentation on how to use -the SDK to build applications, please see the `user <../user>`_ section. +the SDK to build applications, please see the `sdk <../sdk>`_ section. -Contribution Mechanics ----------------------- +Setting up Development Environment +---------------------------------- + +The first step towards contributing code and documentation is to setup your +development environment. We use a pretty standard setup, but it is fully +documented in our :doc:`setup ` section. .. toctree:: :maxdepth: 2 - contributing + setup + -Contacting the Developers -------------------------- +Project Layout +-------------- -GitHub -****** +The project contains a top-level ``otcextensions`` package, which houses +several modules that form the foundation upon which each service's API is +built on. Under the ``otcextensions`` package are packages for the +``sdk``, the ``osclient`` (OpenStackClient / CLI) and the related ``tests`` +of each service implementation. Inside of those directories, the custom +created services such as ``Cloud Container Engine (CCE)`` are hosted. -Currently no official communication other than GitHub is available +.. toctree:: -Email -***** + layout -??? Coding Standards ---------------- @@ -38,17 +45,6 @@ good idea to read through the :doc:`coding ` section. coding -Development Environment ------------------------ - -The first step towards contributing code and documentation is to setup your -development environment. We use a pretty standard setup, but it is fully -documented in our :doc:`setup ` section. - -.. toctree:: - :maxdepth: 2 - - setup Testing ------- @@ -63,20 +59,10 @@ the SDK's features and examples against an OpenStack cloud. testing -Project Layout --------------- -The project contains a top-level ``openstack`` package, which houses several -modules that form the foundation upon which each service's API is built on. -Under the ``openstack`` package are packages for each of those services, -such as ``openstack.compute``. -.. toctree:: - - layout - -Adding Features ---------------- +Example SDK Service and Resource Implementation +----------------------------------------------- Does this SDK not do what you need it to do? Is it missing a service? Are you a developer on another project who wants to add their service? You're in the @@ -88,5 +74,11 @@ OpenStack SDK. create/resource -.. TODO(briancurtin): document how to create a proxy -.. TODO(briancurtin): document how to create auth plugins + +Contacting the OTC Extensions Developers +---------------------------------------- + +Currently no official communication other than `GitHub +`_ is available. +Feel free to open new issues if you want to contact us directly or have +questions related to the existent packages. diff --git a/doc/source/index.rst b/doc/source/index.rst index ed8142cef..a9b900285 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -27,12 +27,8 @@ cases. Additionally some auxiliary documentation is available: cli/index sdk/index contributor/index - history - glossary - releasenotes coverage - issues - user/index + appendices/index Installation and Configuration @@ -50,7 +46,7 @@ Working with the CLI tool Users who want to access Open Telekom Cloud specific services with :doc:`command line tools ` for a shell like Bash find -documentation of all of their opetions and properties in this section. +documentation of all of their operations and properties in this section. Writing your own Scripts for the Cloud @@ -58,7 +54,7 @@ Writing your own Scripts for the Cloud Developers, who plan to write own Python code, may access the API more easily by using the OTC Extensions' classes and methods. The -:doc:`architecture and interfaces ` are documented in this +:doc:`SDK interfaces ` are documented in this section. @@ -76,26 +72,21 @@ General Information Adding to that, there is some general background information available: -* In a `glossary`_ important terms and their naming conventions are +* In a :doc:`glossary ` important terms and their naming conventions are described. -* There is a `history`_ explaing the ancestry of this project. This +* There is a :doc:`history ` explaing the ancestry of this project. This may or may not be insightful if you want to understand the projects architecture. -* There is a `release history`_ available. +* There is a :doc:`release history ` available. -* A list of `potential issues`_ is maintained. +* A list of :doc:`issues ` is maintained. -* Currently 13 services are `covered`_ by the OTC extensions. +* Currently 13 services are :doc:`covered ` by the OTC extensions. .. _OpenStack SDK: https://docs.openstack.org/openstacksdk/ .. _OpenStack API: https://docs.openstack.org/api-quick-start/ .. _Open Telekom Cloud: https://open-telekom-cloud.com/ .. _Ansible modules: https://github.com/OpenTelekomCloud/ansible-collections/ .. _OpenStack Client: https://docs.openstack.org/python-openstackclient/ -.. _glossary: -.. _history: -.. _release history: -.. _potential issues: -.. _covered: diff --git a/doc/source/sdk/getting_started.rst b/doc/source/sdk/getting_started.rst index bebdab984..fc9a46040 100644 --- a/doc/source/sdk/getting_started.rst +++ b/doc/source/sdk/getting_started.rst @@ -7,9 +7,9 @@ Connect to the cloud In order to work with an OpenStack cloud you first need to create a :class:`~openstack.connection.Connection` using your credentials. A :class:`~openstack.connection.Connection` can be created in three -ways, using the class itself, :ref:`config-clouds-yaml`, or -:ref:`config-environment-variables`. It is recommended use -:ref:`config-clouds-yaml` as the same config can be used across tools +ways, using the class itself, config-clouds-yaml (LABEL), or +config-environment-variables (LABEL). It is recommended use +config-clouds-yaml (LABEL) as the same config can be used across tools and languages. Examples are the OpenStack Client, the Gophercloud library for golang, and Terraform that is based on that library. Please be also aware that environment variables carrying diff --git a/doc/source/sdk/proxies/auto_scaling.rst b/doc/source/sdk/proxies/auto_scaling.rst index c28d501e4..ed26c27af 100644 --- a/doc/source/sdk/proxies/auto_scaling.rst +++ b/doc/source/sdk/proxies/auto_scaling.rst @@ -1,7 +1,7 @@ AutoScaling API =============== -For details on how to use auto scaling, see :doc:`/user/guides/auto_scaling` +For details on how to use auto scaling, see /sdk/guides/auto_scaling (NEEDS TO BE DONE) .. automodule:: otcextensions.sdk.auto_scaling.v1._proxy diff --git a/doc/source/sdk/proxies/obs.rst b/doc/source/sdk/proxies/obs.rst index e23e34c89..218c15806 100644 --- a/doc/source/sdk/proxies/obs.rst +++ b/doc/source/sdk/proxies/obs.rst @@ -1,7 +1,7 @@ ObjectBlockStorage OBS API ========================== -For details on how to use database, see :doc:`/user/guides/obs` +For details on how to use database, see /user/guides/obs (NEEDS TO BE DONE) .. automodule:: otcextensions.sdk.obs.v1._proxy diff --git a/doc/source/sdk/proxies/rds_v1.rst b/doc/source/sdk/proxies/rds_v1.rst index 55b991b86..76559f583 100644 --- a/doc/source/sdk/proxies/rds_v1.rst +++ b/doc/source/sdk/proxies/rds_v1.rst @@ -1,7 +1,7 @@ Database RDS API ================ -For details on how to use database, see :doc:`/user/guides/rds` +For details on how to use database, see /user/guides/rds (NEEDS TO BE DONE) .. automodule:: otcextensions.sdk.rds.v1._proxy diff --git a/doc/source/sdk/proxies/rds_v3.rst b/doc/source/sdk/proxies/rds_v3.rst index c5240b482..b75b39e44 100644 --- a/doc/source/sdk/proxies/rds_v3.rst +++ b/doc/source/sdk/proxies/rds_v3.rst @@ -1,7 +1,7 @@ Database RDS API ================ -For details on how to use database, see :doc:`/user/guides/rds` +For details on how to use database, see /sdk/guides/rds (NEEDS TO BE DONE) .. automodule:: otcextensions.sdk.rds.v3._proxy diff --git a/doc/source/sdk/proxies/volume_backup.rst b/doc/source/sdk/proxies/volume_backup.rst index 2802809b7..ede7783d6 100644 --- a/doc/source/sdk/proxies/volume_backup.rst +++ b/doc/source/sdk/proxies/volume_backup.rst @@ -1,7 +1,7 @@ VolumeBackup API ================ -For details on how to use auto scaling, see :doc:`/user/guides/volume_backup` +For details on how to use auto scaling, see /sdk/guides/volume_backup (NEEDS TO BE DONE) .. automodule:: otcextensions.sdk.volume_backup.v2._proxy diff --git a/doc/source/user/config/configuration.rst b/doc/source/user/config/configuration.rst deleted file mode 100644 index 1cdd0ec10..000000000 --- a/doc/source/user/config/configuration.rst +++ /dev/null @@ -1,322 +0,0 @@ -.. _openstack-config: - -====================================== -Configuring OpenStack SDK Applications -====================================== - -.. _config-environment-variables: - -Environment Variables ---------------------- - -`openstacksdk` honors all of the normal `OS_*` variables. It does not -provide backwards compatibility to service-specific variables such as -`NOVA_USERNAME`. - -If you have OpenStack environment variables set, `openstacksdk` will -produce a cloud config object named `envvars` containing your values from the -environment. If you don't like the name `envvars`, that's ok, you can override -it by setting `OS_CLOUD_NAME`. - -Service specific settings, like the nova service type, are set with the -default service type as a prefix. For instance, to set a special service_type -for trove set - -.. code-block:: bash - - export OS_DATABASE_SERVICE_TYPE=rax:database - -.. _config-clouds-yaml: - -Config Files ------------- - -`openstacksdk` will look for a file called `clouds.yaml` in the following -locations: - -* Current Directory -* ~/.config/openstack -* /etc/openstack - -The first file found wins. - -You can also set the environment variable `OS_CLIENT_CONFIG_FILE` to an -absolute path of a file to look for and that location will be inserted at the -front of the file search list. - -The keys are all of the keys you'd expect from `OS_*` - except lower case -and without the OS prefix. So, region name is set with `region_name`. - -Service specific settings, like the nova service type, are set with the -default service type as a prefix. For instance, to set a special service_type -for trove (because you're using Rackspace) set: - -.. code-block:: yaml - - database_service_type: 'rax:database' - - -Site Specific File Locations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In addition to `~/.config/openstack` and `/etc/openstack` - some platforms -have other locations they like to put things. `openstacksdk` will also -look in an OS specific config dir - -* `USER_CONFIG_DIR` -* `SITE_CONFIG_DIR` - -`USER_CONFIG_DIR` is different on Linux, OSX and Windows. - -* Linux: `~/.config/openstack` -* OSX: `~/Library/Application Support/openstack` -* Windows: `C:\\Users\\USERNAME\\AppData\\Local\\OpenStack\\openstack` - -`SITE_CONFIG_DIR` is different on Linux, OSX and Windows. - -* Linux: `/etc/openstack` -* OSX: `/Library/Application Support/openstack` -* Windows: `C:\\ProgramData\\OpenStack\\openstack` - -An example config file is probably helpful: - -.. code-block:: yaml - - clouds: - mtvexx: - profile: vexxhost - auth: - username: mordred@inaugust.com - password: XXXXXXXXX - project_name: mordred@inaugust.com - region_name: ca-ymq-1 - dns_api_version: 1 - mordred: - region_name: RegionOne - auth: - username: 'mordred' - password: XXXXXXX - project_name: 'shade' - auth_url: 'https://montytaylor-sjc.openstack.blueboxgrid.com:5001/v2.0' - infra: - profile: rackspace - auth: - username: openstackci - password: XXXXXXXX - project_id: 610275 - regions: - - DFW - - ORD - - IAD - -You may note a few things. First, since `auth_url` settings are silly -and embarrassingly ugly, known cloud vendor profile information is included and -may be referenced by name. One of the benefits of that is that `auth_url` -isn't the only thing the vendor defaults contain. For instance, since -Rackspace lists `rax:database` as the service type for trove, `openstacksdk` -knows that so that you don't have to. In case the cloud vendor profile is not -available, you can provide one called `clouds-public.yaml`, following the same -location rules previously mentioned for the config files. - -`regions` can be a list of regions. When you call `get_all_clouds`, -you'll get a cloud config object for each cloud/region combo. - -As seen with `dns_service_type`, any setting that makes sense to be -per-service, like `service_type` or `endpoint` or `api_version` can be set -by prefixing the setting with the default service type. That might strike you -funny when setting `service_type` and it does me too - but that's just the -world we live in. - -Auth Settings -------------- - -Keystone has auth plugins - which means it's not possible to know ahead of time -which auth settings are needed. `openstacksdk` sets the default plugin type -to `password`, which is what things all were before plugins came about. In -order to facilitate validation of values, all of the parameters that exist -as a result of a chosen plugin need to go into the auth dict. For password -auth, this includes `auth_url`, `username` and `password` as well as anything -related to domains, projects and trusts. - -Splitting Secrets ------------------ - -In some scenarios, such as configuration management controlled environments, -it might be easier to have secrets in one file and non-secrets in another. -This is fully supported via an optional file `secure.yaml` which follows all -the same location rules as `clouds.yaml`. It can contain anything you put -in `clouds.yaml` and will take precedence over anything in the `clouds.yaml` -file. - -.. code-block:: yaml - - # clouds.yaml - clouds: - internap: - profile: internap - auth: - username: api-55f9a00fb2619 - project_name: inap-17037 - regions: - - ams01 - - nyj01 - # secure.yaml - clouds: - internap: - auth: - password: XXXXXXXXXXXXXXXXX - -SSL Settings ------------- - -When the access to a cloud is done via a secure connection, `openstacksdk` -will always verify the SSL cert by default. This can be disabled by setting -`verify` to `False`. In case the cert is signed by an unknown CA, a specific -cacert can be provided via `cacert`. **WARNING:** `verify` will always have -precedence over `cacert`, so when setting a CA cert but disabling `verify`, the -cloud cert will never be validated. - -Client certs are also configurable. `cert` will be the client cert file -location. In case the cert key is not included within the client cert file, -its file location needs to be set via `key`. - -.. code-block:: yaml - - # clouds.yaml - clouds: - regular-secure-cloud: - auth: - auth_url: https://signed.cert.domain:5000 - ... - unknown-ca-with-client-cert-secure-cloud: - auth: - auth_url: https://unknown.ca.but.secure.domain:5000 - ... - key: /home/myhome/client-cert.key - cert: /home/myhome/client-cert.crt - cacert: /home/myhome/ca.crt - self-signed-insecure-cloud: - auth: - auth_url: https://self.signed.cert.domain:5000 - ... - verify: False - -Note for parity with ``openstack`` command-line options the `insecure` -boolean is also recognised (with the opposite semantics to `verify`; -i.e. `True` ignores certificate failures). This should be considered -deprecated for `verify`. - -Cache Settings --------------- - -Accessing a cloud is often expensive, so it's quite common to want to do some -client-side caching of those operations. To facilitate that, `openstacksdk` -understands passing through cache settings to dogpile.cache, with the following -behaviors: - -* Listing no config settings means you get a null cache. -* `cache.expiration_time` and nothing else gets you memory cache. -* Otherwise, `cache.class` and `cache.arguments` are passed in - -Different cloud behaviors are also differently expensive to deal with. If you -want to get really crazy and tweak stuff, you can specify different expiration -times on a per-resource basis by passing values, in seconds to an expiration -mapping keyed on the singular name of the resource. A value of `-1` indicates -that the resource should never expire. - -`openstacksdk` does not actually cache anything itself, but it collects -and presents the cache information so that your various applications that -are connecting to OpenStack can share a cache should you desire. - -.. code-block:: yaml - - cache: - class: dogpile.cache.pylibmc - expiration_time: 3600 - arguments: - url: - - 127.0.0.1 - expiration: - server: 5 - flavor: -1 - clouds: - mtvexx: - profile: vexxhost - auth: - username: mordred@inaugust.com - password: XXXXXXXXX - project_name: mordred@inaugust.com - region_name: ca-ymq-1 - dns_api_version: 1 - - -IPv6 ----- - -IPv6 is the future, and you should always use it if your cloud supports it and -if your local network supports it. Both of those are easily detectable and all -friendly software should do the right thing. However, sometimes you might -exist in a location where you have an IPv6 stack, but something evil has -caused it to not actually function. In that case, there is a config option -you can set to unbreak you `force_ipv4`, or `OS_FORCE_IPV4` boolean -environment variable. - -.. code-block:: yaml - - client: - force_ipv4: true - clouds: - mtvexx: - profile: vexxhost - auth: - username: mordred@inaugust.com - password: XXXXXXXXX - project_name: mordred@inaugust.com - region_name: ca-ymq-1 - dns_api_version: 1 - monty: - profile: rax - auth: - username: mordred@inaugust.com - password: XXXXXXXXX - project_name: mordred@inaugust.com - region_name: DFW - -The above snippet will tell client programs to prefer returning an IPv4 -address. - -Per-region settings -------------------- - -Sometimes you have a cloud provider that has config that is common to the -cloud, but also with some things you might want to express on a per-region -basis. For instance, Internap provides a public and private network specific -to the user in each region, and putting the values of those networks into -config can make consuming programs more efficient. - -To support this, the region list can actually be a list of dicts, and any -setting that can be set at the cloud level can be overridden for that -region. - -.. code-block:: yaml - - clouds: - internap: - profile: internap - auth: - password: XXXXXXXXXXXXXXXXX - username: api-55f9a00fb2619 - project_name: inap-17037 - regions: - - name: ams01 - values: - networks: - - name: inap-17037-WAN1654 - routes_externally: true - - name: inap-17037-LAN6745 - - name: nyj01 - values: - networks: - - name: inap-17037-WAN1654 - routes_externally: true - - name: inap-17037-LAN6745 diff --git a/doc/source/user/config/index.rst b/doc/source/user/config/index.rst deleted file mode 100644 index 11637239d..000000000 --- a/doc/source/user/config/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -====================== -Using os-client-config -====================== - -.. toctree:: - :maxdepth: 2 - - configuration - using - vendor-support - network-config - reference diff --git a/doc/source/user/config/network-config.rst b/doc/source/user/config/network-config.rst deleted file mode 100644 index ea8541478..000000000 --- a/doc/source/user/config/network-config.rst +++ /dev/null @@ -1,67 +0,0 @@ -============== -Network Config -============== - -There are several different qualities that networks in OpenStack might have -that might not be able to be automatically inferred from the available -metadata. To help users navigate more complex setups, `os-client-config` -allows configuring a list of network metadata. - -.. code-block:: yaml - - clouds: - amazing: - networks: - - name: blue - routes_externally: true - - name: purple - routes_externally: true - default_interface: true - - name: green - routes_externally: false - - name: yellow - routes_externally: false - nat_destination: true - - name: chartreuse - routes_externally: false - routes_ipv6_externally: true - - name: aubergine - routes_ipv4_externally: false - routes_ipv6_externally: true - -Every entry must have a name field, which can hold either the name or the id -of the network. - -`routes_externally` is a boolean field that labels the network as handling -north/south traffic off of the cloud. In a public cloud this might be thought -of as the "public" network, but in private clouds it's possible it might -be an RFC1918 address. In either case, it's provides IPs to servers that -things not on the cloud can use. This value defaults to `false`, which -indicates only servers on the same network can talk to it. - -`routes_ipv4_externally` and `routes_ipv6_externally` are boolean fields to -help handle `routes_externally` in the case where a network has a split stack -with different values for IPv4 and IPv6. Either entry, if not given, defaults -to the value of `routes_externally`. - -`default_interface` is a boolean field that indicates that the network is the -one that programs should use. It defaults to false. An example of needing to -use this value is a cloud with two private networks, and where a user is -running ansible in one of the servers to talk to other servers on the private -network. Because both networks are private, there would otherwise be no way -to determine which one should be used for the traffic. There can only be one -`default_interface` per cloud. - -`nat_destination` is a boolean field that indicates which network floating -ips should be attached to. It defaults to false. Normally this can be inferred -by looking for a network that has subnets that have a gateway_ip. But it's -possible to have more than one network that satisfies that condition, so the -user might want to tell programs which one to pick. There can be only one -`nat_destination` per cloud. - -`nat_source` is a boolean field that indicates which network floating -ips should be requested from. It defaults to false. Normally this can be -inferred by looking for a network that is attached to a router. But it's -possible to have more than one network that satisfies that condition, so the -user might want to tell programs which one to pick. There can be only one -`nat_source` per cloud. diff --git a/doc/source/user/config/reference.rst b/doc/source/user/config/reference.rst deleted file mode 100644 index b4909ad32..000000000 --- a/doc/source/user/config/reference.rst +++ /dev/null @@ -1,14 +0,0 @@ -============= -API Reference -============= - -.. module:: openstack.config - :synopsis: OpenStack client configuration - -.. autoclass:: openstack.config.OpenStackConfig - :members: - :inherited-members: - -.. autoclass:: openstack.config.cloud_region.CloudRegion - :members: - :inherited-members: diff --git a/doc/source/user/config/using.rst b/doc/source/user/config/using.rst deleted file mode 100644 index 7792989cf..000000000 --- a/doc/source/user/config/using.rst +++ /dev/null @@ -1,58 +0,0 @@ -======================================== -Using openstack.config in an Application -======================================== - -Usage ------ - -The simplest and least useful thing you can do is: - -.. code-block:: python - - python -m openstack.config.loader - -Which will print out whatever if finds for your config. If you want to use -it from python, which is much more likely what you want to do, things like: - -Get a named cloud. - -.. code-block:: python - - import openstack.config - - cloud_region = openstack.config.OpenStackConfig().get_one( - 'internap', region_name='ams01') - print(cloud_region.name, cloud_region.region, cloud_region.config) - -Or, get all of the clouds. - -.. code-block:: python - - import openstack.config - - cloud_regions = openstack.config.OpenStackConfig().get_all() - for cloud_region in cloud_regions: - print(cloud_region.name, cloud_region.region, cloud_region.config) - -argparse --------- - -If you're using `openstack.config` from a program that wants to process -command line options, there is a registration function to register the -arguments that both `openstack.config` and keystoneauth know how to deal -with - as well as a consumption argument. - -.. code-block:: python - - import argparse - import sys - - import openstack.config - - config = openstack.config.OpenStackConfig() - parser = argparse.ArgumentParser() - config.register_argparse_arguments(parser, sys.argv) - - options = parser.parse_args() - - cloud_region = config.get_one(argparse=options) diff --git a/doc/source/user/config/vendor-support.rst b/doc/source/user/config/vendor-support.rst deleted file mode 100644 index 4143da248..000000000 --- a/doc/source/user/config/vendor-support.rst +++ /dev/null @@ -1,343 +0,0 @@ -============== -Vendor Support -============== - -OpenStack presents deployers with many options, some of which can expose -differences to end users. `os-client-config` tries its best to collect -information about various things a user would need to know. The following -is a text representation of the vendor related defaults `os-client-config` -knows about. - -Default Values --------------- - -These are the default behaviors unless a cloud is configured differently. - -* Identity uses `password` authentication -* Identity API Version is 2 -* Image API Version is 2 -* Volume API Version is 2 -* Compute API Version is 2.1 -* Images must be in `qcow2` format -* Images are uploaded using PUT interface -* Public IPv4 is directly routable via DHCP from Neutron -* IPv6 is not provided -* Floating IPs are not required -* Floating IPs are provided by Neutron -* Security groups are provided by Neutron -* Vendor specific agents are not used - -AURO ----- - -https://api.auro.io:5000/v2.0 - -============== ================ -Region Name Location -============== ================ -van1 Vancouver, BC -============== ================ - -* Public IPv4 is provided via NAT with Neutron Floating IP - -Betacloud ---------- - -https://api-1.betacloud.io:5000 - -============== ================== -Region Name Location -============== ================== -betacloud-1 Nuremberg, Germany -============== ================== - -* Identity API Version is 3 -* Images must be in `raw` format -* Public IPv4 is provided via NAT with Neutron Floating IP -* Volume API Version is 3 - -Catalyst --------- - -https://api.cloud.catalyst.net.nz:5000/v2.0 - -============== ================ -Region Name Location -============== ================ -nz-por-1 Porirua, NZ -nz_wlg_2 Wellington, NZ -============== ================ - -* Identity API Version is 3 -* Compute API Version is 2 -* Images must be in `raw` format -* Volume API Version is 3 - -City Cloud ----------- - -https://identity1.citycloud.com:5000/v3/ - -============== ================ -Region Name Location -============== ================ -Buf1 Buffalo, NY -Fra1 Frankfurt, DE -Kna1 Karlskrona, SE -La1 Los Angeles, CA -Lon1 London, UK -Sto2 Stockholm, SE -============== ================ - -* Identity API Version is 3 -* Public IPv4 is provided via NAT with Neutron Floating IP -* Volume API Version is 1 - -ConoHa ------- - -https://identity.%(region_name)s.conoha.io - -============== ================ -Region Name Location -============== ================ -tyo1 Tokyo, JP -sin1 Singapore -sjc1 San Jose, CA -============== ================ - -* Image upload is not supported - -DreamCompute ------------- - -https://iad2.dream.io:5000 - -============== ================ -Region Name Location -============== ================ -RegionOne Ashburn, VA -============== ================ - -* Identity API Version is 3 -* Images must be in `raw` format -* IPv6 is provided to every server - -Open Telekom Cloud ------------------- - -https://iam.%(region_name)s.otc.t-systems.com/v3 - -============== ================ -Region Name Location -============== ================ -eu-de Germany -============== ================ - -* Identity API Version is 3 -* Images must be in `vhd` format -* Public IPv4 is provided via NAT with Neutron Floating IP - -ELASTX ------- - -https://ops.elastx.net:5000/v2.0 - -============== ================ -Region Name Location -============== ================ -regionOne Stockholm, SE -============== ================ - -* Public IPv4 is provided via NAT with Neutron Floating IP - -Enter Cloud Suite ------------------ - -https://api.entercloudsuite.com/v2.0 - -============== ================ -Region Name Location -============== ================ -nl-ams1 Amsterdam, NL -it-mil1 Milan, IT -de-fra1 Frankfurt, DE -============== ================ - -* Compute API Version is 2 - -Fuga ----- - -https://identity.api.fuga.io:5000 - -============== ================ -Region Name Location -============== ================ -cystack Netherlands -============== ================ - -* Identity API Version is 3 -* Volume API Version is 3 - -Internap --------- - -https://identity.api.cloud.iweb.com/v2.0 - -============== ================ -Region Name Location -============== ================ -ams01 Amsterdam, NL -da01 Dallas, TX -nyj01 New York, NY -sin01 Singapore -sjc01 San Jose, CA -============== ================ - -* Floating IPs are not supported - -Limestone Networks ------------------- - -https://auth.cloud.lstn.net:5000/v3 - -============== ================== -Region Name Location -============== ================== -us-dfw-1 Dallas, TX -us-slc Salt Lake City, UT -============== ================== - -* Identity API Version is 3 -* Images must be in `raw` format -* IPv6 is provided to every server connected to the `Public Internet` network - -OVH ---- - -https://auth.cloud.ovh.net/v2.0 - -============== ================ -Region Name Location -============== ================ -BHS1 Beauharnois, QC -SBG1 Strassbourg, FR -GRA1 Gravelines, FR -============== ================ - -* Images may be in `raw` format. The `qcow2` default is also supported -* Floating IPs are not supported - -Rackspace ---------- - -https://identity.api.rackspacecloud.com/v2.0/ - -============== ================ -Region Name Location -============== ================ -DFW Dallas, TX -HKG Hong Kong -IAD Washington, D.C. -LON London, UK -ORD Chicago, IL -SYD Sydney, NSW -============== ================ - -* Database Service Type is `rax:database` -* Compute Service Name is `cloudServersOpenStack` -* Images must be in `vhd` format -* Images must be uploaded using the Glance Task Interface -* Floating IPs are not supported -* Public IPv4 is directly routable via static config by Nova -* IPv6 is provided to every server -* Security groups are not supported -* Uploaded Images need properties to not use vendor agent:: - :vm_mode: hvm - :xenapi_use_agent: False -* Volume API Version is 1 -* While passwords are recommended for use, API keys do work as well. - The `rackspaceauth` python package must be installed, and then the following - can be added to clouds.yaml:: - - auth: - username: myusername - api_key: myapikey - auth_type: rackspace_apikey - -SWITCHengines -------------- - -https://keystone.cloud.switch.ch:5000/v2.0 - -============== ================ -Region Name Location -============== ================ -LS Lausanne, CH -ZH Zurich, CH -============== ================ - -* Identity API Version is 3 -* Compute API Version is 2 -* Images must be in `raw` format -* Volume API Version is 3 - -Ultimum -------- - -https://console.ultimum-cloud.com:5000/v2.0 - -============== ================ -Region Name Location -============== ================ -RegionOne Prague, CZ -============== ================ - -* Volume API Version is 1 - -UnitedStack ------------ - -https://identity.api.ustack.com/v3 - -============== ================ -Region Name Location -============== ================ -bj1 Beijing, CN -gd1 Guangdong, CN -============== ================ - -* Identity API Version is 3 -* Images must be in `raw` format -* Volume API Version is 1 - -VEXXHOST --------- - -http://auth.vexxhost.net - -============== ================ -Region Name Location -============== ================ -ca-ymq-1 Montreal, QC -sjc1 Santa Clara, CA -============== ================ - -* DNS API Version is 1 -* Identity API Version is 3 -* Volume API Version is 3 - -Zetta ------ - -https://identity.api.zetta.io/v3 - -============== ================ -Region Name Location -============== ================ -no-osl1 Oslo, NO -============== ================ - -* DNS API Version is 2 -* Identity API Version is 3 diff --git a/doc/source/user/connection.rst b/doc/source/user/connection.rst deleted file mode 100644 index 9ce3452f5..000000000 --- a/doc/source/user/connection.rst +++ /dev/null @@ -1,31 +0,0 @@ -Connection -========== -.. automodule:: openstack.connection - - from_config - ----------- - .. autofunction:: openstack.connection.from_config - -Registering OTC extensions -========================== - -.. autofunction:: otcextensions.sdk.register_otc_extensions - -Connection Object ------------------ - -.. autoclass:: openstack.connection.Connection - :members: - :inherited-members: - - -Transitioning from Profile --------------------------- - -Support exists for users coming from older releases of OpenStack SDK who have -been using the :class:`~openstack.profile.Profile` interface. - -.. toctree:: - :maxdepth: 1 - - transition_from_profile diff --git a/doc/source/user/examples b/doc/source/user/examples deleted file mode 120000 index 9f9d1de88..000000000 --- a/doc/source/user/examples +++ /dev/null @@ -1 +0,0 @@ -../../../examples \ No newline at end of file diff --git a/doc/source/user/guides/auto_scaling.rst b/doc/source/user/guides/auto_scaling.rst deleted file mode 100644 index 10c805c9d..000000000 --- a/doc/source/user/guides/auto_scaling.rst +++ /dev/null @@ -1,4 +0,0 @@ -Using OTC AS -============ - -.. TODO(agoncharov): Implement this guide diff --git a/doc/source/user/guides/connect_otc.rst b/doc/source/user/guides/connect_otc.rst deleted file mode 100644 index e7a7b7398..000000000 --- a/doc/source/user/guides/connect_otc.rst +++ /dev/null @@ -1,39 +0,0 @@ -Connect to the cloud -==================== - -In order to work with an OpenStack cloud you first need to create a -:class:`~openstack.connection.Connection` using your credentials. A -:class:`~openstack.connection.Connection` can be created in three -ways, using the class itself, :ref:`config-clouds-yaml`, or -:ref:`config-environment-variables`. It is recommended use -:ref:`config-clouds-yaml` as the same config can be used across tools -and languages. Examples are the OpenStack Client, the Gophercloud -library for golang, and Terraform that is based on that -library. Please be also aware that environment variables carrying -credentials can be a security risk. - -Create Connection ------------------ - -To create a :class:`~openstack.connection.Connection` instance, use the -:func:`~openstack.connect` factory function. - -As a next step inject the OTC Extensions into the retrieved connection - -.. code-block:: python - - # An 'otc' is a cloud connection with name 'otc' configured in the clouds.yaml - conn = openstack.connect(cloud='otc') - - # Register OTC Extensions - sdk.register_otc_extensions(conn) - -See a full example at `connect_otc.py `_ - -.. note:: To enable logging, see the :doc:`logging` user guide. - -Next ----- - -Now that you can create a connection, continue with the :ref:`user_guides` -to work with an OpenStack service. diff --git a/doc/source/user/guides/deh.rst b/doc/source/user/guides/deh.rst deleted file mode 100644 index 81ce7493e..000000000 --- a/doc/source/user/guides/deh.rst +++ /dev/null @@ -1,73 +0,0 @@ -Using OTC DeH -============= - -Before working with the Dedicated Host service, you'll need to create a -connection to your OTC cloud account by following the :doc:`connect_otc` user -guide. This will provide you with the ``conn`` variable used in the examples -below. - -.. contents:: Table of Contents - :local: - -The primary resource of the DeH service is the **host**. - -CRUD operations -~~~~~~~~~~~~~~~ - -List Hosts ----------- - -A **host** is a dedicated host, where virtual machines would be running. - -.. literalinclude:: ../examples/deh/list.py - :pyobject: list_hosts - -Full example: `deh host list`_ - -List Hosts Types ----------------- - -In order to allocate a host, it's type need to be chosen first. Types might -differ per availability zone, therefore it is required to specify in which -AZ to look for types - -.. literalinclude:: ../examples/deh/list_types.py - :pyobject: list_host_types - -Full example: `deh host list type`_ - -List Host servers ------------------ - -Each DeH Host is intended to run virtual instances. Only querying list of -servers is supported - -.. literalinclude:: ../examples/deh/list_servers.py - :pyobject: list_host_servers - -Full example: `deh host list server`_ - -Provisioning operations -~~~~~~~~~~~~~~~~~~~~~~~ - -Provisioning actions are the main way to manipulate the hosts. - -Allocating a DeH Host Instance ------------------------------- - -A host can be allocated with a following snip. - -.. literalinclude:: ../examples/deh/create.py - :pyobject: create_host - -Allocating a DeH Host supports setting `quantity` parameter to allocate -multiple hosts in a one call. Due to that the IDs of allocated hosts are being -returned as part of the "virtual" resource in a `dedicated_host_ids` attribute - -Full example: `deh host create`_ - - -.. _deh host list: https://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/list.py -.. _deh host list type: https://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/list_types.py -.. _deh host create: https://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/create.py -.. _deh host list server: https://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/list_servers.py diff --git a/doc/source/user/guides/logging.rst b/doc/source/user/guides/logging.rst deleted file mode 100644 index 7a41b950d..000000000 --- a/doc/source/user/guides/logging.rst +++ /dev/null @@ -1,112 +0,0 @@ -======= -Logging -======= - -.. note:: TODO(shade) This document is written from a shade POV. It needs to - be combined with the existing logging guide, but also the logging - systems need to be rationalized. - -`openstacksdk` uses `Python Logging`_. As `openstacksdk` is a library, it does -not configure logging handlers automatically, expecting instead for that to be -the purview of the consuming application. - -Simple Usage ------------- - -For consumers who just want to get a basic logging setup without thinking -about it too deeply, there is a helper method. If used, it should be called -before any other openstacksdk functionality. - -.. code-block:: python - - import openstack - openstack.enable_logging() - -The ``stream`` parameter controls the stream where log message are written to. -It defaults to `sys.stdout` which will result in log messages being written -to STDOUT. It can be set to another output stream, or to ``None`` to disable -logging to the console. - -The ``path`` parameter sets up logging to log to a file. By default, if -``path`` is given and ``stream`` is not, logging will only go to ``path``. - -You can combine the ``path`` and ``stream`` parameters to log to both places -simultaneously. - -To log messages to a file called ``openstack.log`` and the console on -``stdout``: - -.. code-block:: python - - import sys - import openstack - - openstack.enable_logging( - debug=True, path='openstack.log', stream=sys.stdout) - - -`openstack.enable_logging` also sets up a few other loggers and -squelches some warnings or log messages that are otherwise uninteresting or -unactionable by an openstacksdk user. - -Advanced Usage --------------- - -`openstacksdk` logs to a set of different named loggers. - -Most of the logging is set up to log to the root ``openstack`` logger. -There are additional sub-loggers that are used at times, primarily so that a -user can decide to turn on or off a specific type of logging. They are listed -below. - -openstack.config - Issues pertaining to configuration are logged to the ``openstack.config`` - logger. - -openstack.task_manager - `openstacksdk` uses a Task Manager to perform remote calls. The - ``openstack.task_manager`` logger emits messages at the start and end - of each Task announcing what it is going to run and then what it ran and - how long it took. Logging ``openstack.task_manager`` is a good way to - get a trace of external actions `openstacksdk` is taking without full - `HTTP Tracing`_. - -openstack.iterate_timeout - When `openstacksdk` needs to poll a resource, it does so in a loop that waits - between iterations and ultimately times out. The - ``openstack.iterate_timeout`` logger emits messages for each iteration - indicating it is waiting and for how long. These can be useful to see for - long running tasks so that one can know things are not stuck, but can also - be noisy. - -openstack.fnmatch - `openstacksdk` will try to use `fnmatch`_ on given `name_or_id` arguments. - It's a best effort attempt, so pattern misses are logged to - ``openstack.fnmatch``. A user may not be intending to use an fnmatch - pattern - such as if they are trying to find an image named - ``Fedora 24 [official]``, so these messages are logged separately. - -.. _fnmatch: https://pymotw.com/2/fnmatch/ - -HTTP Tracing ------------- - -HTTP Interactions are handled by `keystoneauth`_. If you want to enable HTTP -tracing while using openstacksdk and are not using `openstack.enable_logging`, -set the log level of the ``keystoneauth`` logger to ``DEBUG``. - -For more information see https://docs.openstack.org/keystoneauth/latest/using-sessions.html#logging - -.. _keystoneauth: https://docs.openstack.org/keystoneauth/latest/ - -Python Logging --------------- - -Python logging is a standard feature of Python and is documented fully in the -Python Documentation, which varies by version of Python. - -For more information on Python Logging for Python v2, see -https://docs.python.org/2/library/logging.html. - -For more information on Python Logging for Python v3, see -https://docs.python.org/3/library/logging.html. diff --git a/doc/source/user/guides/obs.rst b/doc/source/user/guides/obs.rst deleted file mode 100644 index 89ffc0f71..000000000 --- a/doc/source/user/guides/obs.rst +++ /dev/null @@ -1,4 +0,0 @@ -Using OTC OBS -============= - -.. TODO(agoncharov): Implement this guide diff --git a/doc/source/user/guides/rds.rst b/doc/source/user/guides/rds.rst deleted file mode 100644 index c7512a459..000000000 --- a/doc/source/user/guides/rds.rst +++ /dev/null @@ -1,4 +0,0 @@ -Using OTC RDS -============= - -.. TODO(agoncharov): Implement this guide diff --git a/doc/source/user/guides/volume_backup.rst b/doc/source/user/guides/volume_backup.rst deleted file mode 100644 index d2a5be6f8..000000000 --- a/doc/source/user/guides/volume_backup.rst +++ /dev/null @@ -1,4 +0,0 @@ -Using OTC VBS -============= - -.. TODO(agoncharov): Implement this guide diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst deleted file mode 100644 index d8c15fb0a..000000000 --- a/doc/source/user/index.rst +++ /dev/null @@ -1,143 +0,0 @@ -Getting started with the OTCExtensions SDK -========================================== - -Please note that OTCExtensions provides an extension to the OpenStackSDK. -Please refer to it's documentation for the details - - - -User Guides ------------ - -These guides walk you through how to make use of the libraries we provide -to work with each OpenStack service. If you're looking for a cookbook -approach, this is where you'll want to begin. - -.. toctree:: - :maxdepth: 1 - - Plain-simple connect to OTC - Configuration - Connect to an OpenStack Cloud Using a Config File - Using Cloud Abstration Layer - Logging - Microversions - Block Storage - Compute - Identity - Image - Key Manager - Message - Network - Object Store - Orchestration - RDS - OBS - AutoScaling - Volume Backup - Dedicated Host - -API Documentation ------------------ - -OpenStackSDK documentation is available under - - -Service APIs are exposed through a two-layered approach. The classes -exposed through our `Connection Interface`_ are -the place to start if you're an application developer consuming an OpenStack -cloud. The `Resource Interface`_ is the layer upon which the -`Connection Interface`_ is built, with methods on Service Proxies accepting -and returning :class:`~openstack.resource.Resource` objects. - -The Cloud Abstraction layer has a data model. - -.. toctree:: - :maxdepth: 1 - - model - -Connection Interface -~~~~~~~~~~~~~~~~~~~~ - -A :class:`~openstack.connection.Connection` instance maintains your cloud -config, session and authentication information providing you with a set of -higher-level interfaces to work with OpenStack services. - -.. toctree:: - :maxdepth: 1 - - connection - -Once you have a :class:`~openstack.connection.Connection` instance, services -are accessed through instances of :class:`~openstack.proxy.Proxy` or -subclasses of it that exist as attributes on the -:class:`~openstack.connection.Connection`. - -.. autoclass:: openstack.proxy.Proxy - :members: - -Resource Interface -~~~~~~~~~~~~~~~~~~ - -The *Resource* layer is a lower-level interface to -communicate with OpenStack services. While the classes exposed by the -Service Proxies build a convenience layer on top of -this, :class:`~openstack.resource.Resource` objects can be -used directly. However, the most common usage of this layer is in receiving -an object from a class in the `Connection Interface_`, modifying it, and -sending it back to the Service Proxies layer, such as to update a resource -on the server. - -The following services have exposed :class:`~openstack.resource.Resource` -classes. - -.. toctree:: - :maxdepth: 1 - - Baremetal - Block Storage - Clustering - Compute - Database - Identity - Image - Key Management - Load Balancer - Network - Orchestration - Object Store - Workflow - Anti DDoS Service - AutoScaling Service - DNS Service - Cloud Container Engine - Cloud Trace Service - Distributed Cache Service - Dedicated Host Service - Distributed Message Service - Key Management Service - Object Block Storage - RDS - -Low-Level Classes -~~~~~~~~~~~~~~~~~ - -The following classes are not commonly used by application developers, -but are used to construct applications to talk to OpenStack APIs. Typically -these parts are managed through the `Connection Interface`_, but their use -can be customized. - -.. toctree:: - :maxdepth: 1 - - resource - utils - -Presentations -============= - -.. toctree:: - :maxdepth: 1 - - multi-cloud-demo diff --git a/doc/source/user/model.rst b/doc/source/user/model.rst deleted file mode 100644 index 62fa748ef..000000000 --- a/doc/source/user/model.rst +++ /dev/null @@ -1,533 +0,0 @@ -========== -Data Model -========== - -shade has a very strict policy on not breaking backwards compatability ever. -However, with the data structures returned from OpenStack, there are places -where the resource structures from OpenStack are returned to the user somewhat -directly, leaving a shade user open to changes/differences in result content. - -To combat that, shade 'normalizes' the return structure from OpenStack in many -places, and the results of that normalization are listed below. Where shade -performs normalization, a user can count on any fields declared in the docs -as being completely safe to use - they are as much a part of shade's API -contract as any other Python method. - -Some OpenStack objects allow for arbitrary attributes at -the root of the object. shade will pass those through so as not to break anyone -who may be counting on them, but as they are arbitrary shade can make no -guarantees as to their existence. As part of normalization, shade will put any -attribute from an OpenStack resource that is not in its data model contract -into an attribute called 'properties'. The contents of properties are -defined to be an arbitrary collection of key value pairs with no promises as -to any particular key ever existing. - -If a user passes `strict=True` to the shade constructor, shade will not pass -through arbitrary objects to the root of the resource, and will instead only -put them in the properties dict. If a user is worried about accidentally -writing code that depends on an attribute that is not part of the API contract, -this can be a useful tool. Keep in mind all data can still be accessed via -the properties dict, but any code touching anything in the properties dict -should be aware that the keys found there are highly user/cloud specific. -Any key that is transformed as part of the shade data model contract will -not wind up with an entry in properties - only keys that are unknown. - -Location --------- - -A Location defines where a resource lives. It includes a cloud name and a -region name, an availability zone as well as information about the project -that owns the resource. - -The project information may contain a project id, or a combination of one or -more of a project name with a domain name or id. If a project id is present, -it should be considered correct. - -Some resources do not carry ownership information with them. For those, the -project information will be filled in from the project the user currently -has a token for. - -Some resources do not have information about availability zones, or may exist -region wide. Those resources will have None as their availability zone. - -If all of the project information is None, then - -.. code-block:: python - - Location = dict( - cloud=str(), - region_name=str(), - zone=str() or None, - project=dict( - id=str() or None, - name=str() or None, - domain_id=str() or None, - domain_name=str() or None)) - - -Resources -========= - -Flavor ------- - -A flavor for a Nova Server. - -.. code-block:: python - - Flavor = dict( - location=Location(), - id=str(), - name=str(), - is_public=bool(), - is_disabled=bool(), - ram=int(), - vcpus=int(), - disk=int(), - ephemeral=int(), - swap=int(), - rxtx_factor=float(), - extra_specs=dict(), - properties=dict()) - - -Flavor Access -------------- - -An access entry for a Nova Flavor. - -.. code-block:: python - - FlavorAccess = dict( - flavor_id=str(), - project_id=str()) - - -Image ------ - -A Glance Image. - -.. code-block:: python - - Image = dict( - location=Location(), - id=str(), - name=str(), - min_ram=int(), - min_disk=int(), - size=int(), - virtual_size=int(), - container_format=str(), - disk_format=str(), - checksum=str(), - created_at=str(), - updated_at=str(), - owner=str(), - is_public=bool(), - is_protected=bool(), - visibility=str(), - status=str(), - locations=list(), - direct_url=str() or None, - tags=list(), - properties=dict()) - - -Keypair -------- - -A keypair for a Nova Server. - -.. code-block:: python - - Keypair = dict( - location=Location(), - name=str(), - id=str(), - public_key=str(), - fingerprint=str(), - type=str(), - user_id=str(), - private_key=str() or None - properties=dict()) - - -Security Group --------------- - -A Security Group from either Nova or Neutron - -.. code-block:: python - - SecurityGroup = dict( - location=Location(), - id=str(), - name=str(), - description=str(), - security_group_rules=list(), - properties=dict()) - -Security Group Rule -------------------- - -A Security Group Rule from either Nova or Neutron - -.. code-block:: python - - SecurityGroupRule = dict( - location=Location(), - id=str(), - direction=str(), # oneof('ingress', 'egress') - ethertype=str(), - port_range_min=int() or None, - port_range_max=int() or None, - protocol=str() or None, - remote_ip_prefix=str() or None, - security_group_id=str() or None, - remote_group_id=str() or None - properties=dict()) - -Server ------- - -A Server from Nova - -.. code-block:: python - - Server = dict( - location=Location(), - id=str(), - name=str(), - image=dict() or str(), - flavor=dict(), - volumes=list(), # Volume - interface_ip=str(), - has_config_drive=bool(), - accessIPv4=str(), - accessIPv6=str(), - addresses=dict(), # string, list(Address) - created=str(), - created_at=str(), - key_name=str(), - metadata=dict(), # string, string - private_v4=str(), - progress=int(), - public_v4=str(), - public_v6=str(), - security_groups=list(), # SecurityGroup - status=str(), - updated=str(), - user_id=str(), - host_id=str() or None, - power_state=str() or None, - task_state=str() or None, - vm_state=str() or None, - launched_at=str() or None, - terminated_at=str() or None, - task_state=str() or None, - properties=dict()) - -ComputeLimits -------------- - -Limits and current usage for a project in Nova - -.. code-block:: python - - ComputeLimits = dict( - location=Location(), - max_personality=int(), - max_personality_size=int(), - max_server_group_members=int(), - max_server_groups=int(), - max_server_meta=int(), - max_total_cores=int(), - max_total_instances=int(), - max_total_keypairs=int(), - max_total_ram_size=int(), - total_cores_used=int(), - total_instances_used=int(), - total_ram_used=int(), - total_server_groups_used=int(), - properties=dict()) - -ComputeUsage ------------- - -Current usage for a project in Nova - -.. code-block:: python - - ComputeUsage = dict( - location=Location(), - started_at=str(), - stopped_at=str(), - server_usages=list(), - max_personality=int(), - max_personality_size=int(), - max_server_group_members=int(), - max_server_groups=int(), - max_server_meta=int(), - max_total_cores=int(), - max_total_instances=int(), - max_total_keypairs=int(), - max_total_ram_size=int(), - total_cores_used=int(), - total_hours=int(), - total_instances_used=int(), - total_local_gb_usage=int(), - total_memory_mb_usage=int(), - total_ram_used=int(), - total_server_groups_used=int(), - total_vcpus_usage=int(), - properties=dict()) - -ServerUsage ------------ - -Current usage for a server in Nova - -.. code-block:: python - - ComputeUsage = dict( - started_at=str(), - ended_at=str(), - flavor=str(), - hours=int(), - instance_id=str(), - local_gb=int(), - memory_mb=int(), - name=str(), - state=str(), - uptime=int(), - vcpus=int(), - properties=dict()) - -Floating IP ------------ - -A Floating IP from Neutron or Nova - - -.. code-block:: python - - FloatingIP = dict( - location=Location(), - id=str(), - description=str(), - attached=bool(), - fixed_ip_address=str() or None, - floating_ip_address=str() or None, - network=str() or None, - port=str() or None, - router=str(), - status=str(), - created_at=str() or None, - updated_at=str() or None, - revision_number=int() or None, - properties=dict()) - -Volume ------- - -A volume from cinder. - -.. code-block:: python - - Volume = dict( - location=Location(), - id=str(), - name=str(), - description=str(), - size=int(), - attachments=list(), - status=str(), - migration_status=str() or None, - host=str() or None, - replication_driver=str() or None, - replication_status=str() or None, - replication_extended_status=str() or None, - snapshot_id=str() or None, - created_at=str(), - updated_at=str() or None, - source_volume_id=str() or None, - consistencygroup_id=str() or None, - volume_type=str() or None, - metadata=dict(), - is_bootable=bool(), - is_encrypted=bool(), - can_multiattach=bool(), - properties=dict()) - - -VolumeType ----------- - -A volume type from cinder. - -.. code-block:: python - - VolumeType = dict( - location=Location(), - id=str(), - name=str(), - description=str() or None, - is_public=bool(), - qos_specs_id=str() or None, - extra_specs=dict(), - properties=dict()) - - -VolumeTypeAccess ----------------- - -A volume type access from cinder. - -.. code-block:: python - - VolumeTypeAccess = dict( - location=Location(), - volume_type_id=str(), - project_id=str(), - properties=dict()) - - -ClusterTemplate ---------------- - -A Cluster Template from magnum. - -.. code-block:: python - - ClusterTemplate = dict( - location=Location(), - apiserver_port=int(), - cluster_distro=str(), - coe=str(), - created_at=str(), - dns_nameserver=str(), - docker_volume_size=int(), - external_network_id=str(), - fixed_network=str() or None, - flavor_id=str(), - http_proxy=str() or None, - https_proxy=str() or None, - id=str(), - image_id=str(), - insecure_registry=str(), - is_public=bool(), - is_registry_enabled=bool(), - is_tls_disabled=bool(), - keypair_id=str(), - labels=dict(), - master_flavor_id=str() or None, - name=str(), - network_driver=str(), - no_proxy=str() or None, - server_type=str(), - updated_at=str() or None, - volume_driver=str(), - properties=dict()) - -MagnumService -------------- - -A Magnum Service from magnum - -.. code-block:: python - - MagnumService = dict( - location=Location(), - binary=str(), - created_at=str(), - disabled_reason=str() or None, - host=str(), - id=str(), - report_count=int(), - state=str(), - properties=dict()) - -Stack ------ - -A Stack from Heat - -.. code-block:: python - - Stack = dict( - location=Location(), - id=str(), - name=str(), - created_at=str(), - deleted_at=str(), - updated_at=str(), - description=str(), - action=str(), - identifier=str(), - is_rollback_enabled=bool(), - notification_topics=list(), - outputs=list(), - owner=str(), - parameters=dict(), - parent=str(), - stack_user_project_id=str(), - status=str(), - status_reason=str(), - tags=dict(), - tempate_description=str(), - timeout_mins=int(), - properties=dict()) - -Identity Resources -================== - -Identity Resources are slightly different. - -They are global to a cloud, so location.availability_zone and -location.region_name and will always be None. If a deployer happens to deploy -OpenStack in such a way that users and projects are not shared amongst regions, -that necessitates treating each of those regions as separate clouds from -shade's POV. - -The Identity Resources that are not Project do not exist within a Project, -so all of the values in ``location.project`` will be None. - -Project -------- - -A Project from Keystone (or a tenant if Keystone v2) - -Location information for Project has some additional specific semantics. -If the project has a parent project, that will be in ``location.project.id``, -and if it doesn't that should be ``None``. - -If the Project is associated with a domain that will be in -``location.project.domain_id`` in addition to the normal ``domain_id`` -regardless of the current user's token scope. - -.. code-block:: python - - Project = dict( - location=Location(), - id=str(), - name=str(), - description=str(), - is_enabled=bool(), - is_domain=bool(), - domain_id=str(), - properties=dict()) - -Role ----- - -A Role from Keystone - -.. code-block:: python - - Project = dict( - location=Location(), - id=str(), - name=str(), - domain_id=str(), - properties=dict()) diff --git a/doc/source/user/multi-cloud-demo.rst b/doc/source/user/multi-cloud-demo.rst deleted file mode 100644 index de529d598..000000000 --- a/doc/source/user/multi-cloud-demo.rst +++ /dev/null @@ -1,809 +0,0 @@ -================ -Multi-Cloud Demo -================ - -This document contains a presentation in `presentty`_ format. If you want to -walk through it like a presentation, install `presentty` and run: - -.. code:: bash - - presentty doc/source/user/multi-cloud-demo.rst - -The content is hopefully helpful even if it's not being narrated, so it's being -included in the `shade` docs. - -.. _presentty: https://pypi.org/project/presentty - -Using Multiple OpenStack Clouds Easily with Shade -================================================= - -Who am I? -========= - -Monty Taylor - -* OpenStack Infra Core -* irc: mordred -* twitter: @e_monty - -What are we going to talk about? -================================ - -`shade` - -* a task and end-user oriented Python library -* abstracts deployment differences -* designed for multi-cloud -* simple to use -* massive scale - - * optional advanced features to handle 20k servers a day - -* Initial logic/design extracted from nodepool -* Librified to re-use in Ansible - -shade is Free Software -====================== - -* https://git.openstack.org/cgit/openstack-infra/shade -* openstack-dev@lists.openstack.org -* #openstack-shade on freenode - -This talk is Free Software, too -=============================== - -* Written for presentty (https://pypi.org/project/presentty) -* doc/source/multi-cloud-demo.rst -* examples in doc/source/examples -* Paths subject to change- this is the first presentation in tree! - -Complete Example -================ - -.. code:: python - - from openstack import cloud as openstack - - # Initialize and turn on debug logging - openstack.enable_logging(debug=True) - - for cloud_name, region_name in [ - ('my-vexxhost', 'ca-ymq-1'), - ('my-citycloud', 'Buf1'), - ('my-internap', 'ams01')]: - # Initialize cloud - cloud = openstack.connect(cloud=cloud_name, region_name=region_name) - - # Upload an image to the cloud - image = cloud.create_image( - 'devuan-jessie', filename='devuan-jessie.qcow2', wait=True) - - # Find a flavor with at least 512M of RAM - flavor = cloud.get_flavor_by_ram(512) - - # Boot a server, wait for it to boot, and then do whatever is needed - # to get a public ip for it. - cloud.create_server( - 'my-server', image=image, flavor=flavor, wait=True, auto_ip=True) - -Let's Take a Few Steps Back -=========================== - -Multi-cloud is easy, but you need to know a few things. - -* Terminology -* Config -* Shade API - -Cloud Terminology -================= - -Let's define a few terms, so that we can use them with ease: - -* `cloud` - logically related collection of services -* `region` - completely independent subset of a given cloud -* `patron` - human who has an account -* `user` - account on a cloud -* `project` - logical collection of cloud resources -* `domain` - collection of users and projects - -Cloud Terminology Relationships -=============================== - -* A `cloud` has one or more `regions` -* A `patron` has one or more `users` -* A `patron` has one or more `projects` -* A `cloud` has one or more `domains` -* In a `cloud` with one `domain` it is named "default" -* Each `patron` may have their own `domain` -* Each `user` is in one `domain` -* Each `project` is in one `domain` -* A `user` has one or more `roles` on one or more `projects` - -HTTP Sessions -============= - -* HTTP interactions are authenticated via keystone -* Authenticating returns a `token` -* An authenticated HTTP Session is shared across a `region` - -Cloud Regions -============= - -A `cloud region` is the basic unit of REST interaction. - -* A `cloud` has a `service catalog` -* The `service catalog` is returned in the `token` -* The `service catalog` lists `endpoint` for each `service` in each `region` -* A `region` is completely autonomous - -Users, Projects and Domains -=========================== - -In clouds with multiple domains, project and user names are -only unique within a region. - -* Names require `domain` information for uniqueness. IDs do not. -* Providing `domain` information when not needed is fine. -* `project_name` requires `project_domain_name` or `project_domain_id` -* `project_id` does not -* `username` requires `user_domain_name` or `user_domain_id` -* `user_id` does not - -Confused Yet? -============= - -Don't worry - you don't have to deal with most of that. - -Auth per cloud, select per region -================================= - -In general, the thing you need to know is: - -* Configure authentication per `cloud` -* Select config to use by `cloud` and `region` - -clouds.yaml -=========== - -Information about the clouds you want to connect to is stored in a file -called `clouds.yaml`. - -`clouds.yaml` can be in your homedir: `~/.config/openstack/clouds.yaml` -or system-wide: `/etc/openstack/clouds.yaml`. - -Information in your homedir, if it exists, takes precedence. - -Full docs on `clouds.yaml` are at -https://docs.openstack.org/os-client-config/latest/ - -What about Mac and Windows? -=========================== - -`USER_CONFIG_DIR` is different on Linux, OSX and Windows. - -* Linux: `~/.config/openstack` -* OSX: `~/Library/Application Support/openstack` -* Windows: `C:\\Users\\USERNAME\\AppData\\Local\\OpenStack\\openstack` - -`SITE_CONFIG_DIR` is different on Linux, OSX and Windows. - -* Linux: `/etc/openstack` -* OSX: `/Library/Application Support/openstack` -* Windows: `C:\\ProgramData\\OpenStack\\openstack` - -Config Terminology -================== - -For multi-cloud, think of two types: - -* `profile` - Facts about the `cloud` that are true for everyone -* `cloud` - Information specific to a given `user` - -Apologies for the use of `cloud` twice. - -Environment Variables and Simple Usage -====================================== - -* Environment variables starting with `OS_` go into a cloud called `envvars` -* If you only have one cloud, you don't have to specify it -* `OS_CLOUD` and `OS_REGION_NAME` are default values for - `cloud` and `region_name` - -TOO MUCH TALKING - NOT ENOUGH CODE -================================== - -basic clouds.yaml for the example code -====================================== - -Simple example of a clouds.yaml - -* Config for a named `cloud` "my-citycloud" -* Reference a well-known "named" profile: `citycloud` -* `os-client-config` has a built-in list of profiles at - https://docs.openstack.org/os-client-config/latest/user/vendor-support.html -* Vendor profiles contain various advanced config -* `cloud` name can match `profile` name (using different names for clarity) - -.. code:: yaml - - clouds: - my-citycloud: - profile: citycloud - auth: - username: mordred - project_id: 65222a4d09ea4c68934fa1028c77f394 - user_domain_id: d0919bd5e8d74e49adf0e145807ffc38 - project_domain_id: d0919bd5e8d74e49adf0e145807ffc38 - -Where's the password? - -secure.yaml -=========== - -* Optional additional file just like `clouds.yaml` -* Values overlaid on `clouds.yaml` -* Useful if you want to protect secrets more stringently - -Example secure.yaml -=================== - -* No, my password isn't XXXXXXXX -* `cloud` name should match `clouds.yaml` -* Optional - I actually keep mine in my `clouds.yaml` - -.. code:: yaml - - clouds: - my-citycloud: - auth: - password: XXXXXXXX - -more clouds.yaml -================ - -More information can be provided. - -* Use v3 of the `identity` API - even if others are present -* Use `https://image-ca-ymq-1.vexxhost.net/v2` for `image` API - instead of what's in the catalog - -.. code:: yaml - - my-vexxhost: - identity_api_version: 3 - image_endpoint_override: https://image-ca-ymq-1.vexxhost.net/v2 - profile: vexxhost - auth: - user_domain_id: default - project_domain_id: default - project_name: d8af8a8f-a573-48e6-898a-af333b970a2d - username: 0b8c435b-cc4d-4e05-8a47-a2ada0539af1 - -Much more complex clouds.yaml example -===================================== - -* Not using a profile - all settings included -* In the `ams01` `region` there are two networks with undiscoverable qualities -* Each one are labeled here so choices can be made -* Any of the settings can be specific to a `region` if needed -* `region` settings override `cloud` settings -* `cloud` does not support `floating-ips` - -.. code:: yaml - - my-internap: - auth: - auth_url: https://identity.api.cloud.iweb.com - username: api-55f9a00fb2619 - project_name: inap-17037 - identity_api_version: 3 - floating_ip_source: None - regions: - - name: ams01 - values: - networks: - - name: inap-17037-WAN1654 - routes_externally: true - default_interface: true - - name: inap-17037-LAN3631 - routes_externally: false - -Complete Example Again -====================== - -.. code:: python - - from openstack import cloud as openstack - - # Initialize and turn on debug logging - openstack.enable_logging(debug=True) - - for cloud_name, region_name in [ - ('my-vexxhost', 'ca-ymq-1'), - ('my-citycloud', 'Buf1'), - ('my-internap', 'ams01')]: - # Initialize cloud - cloud = openstack.connect(cloud=cloud_name, region_name=region_name) - - # Upload an image to the cloud - image = cloud.create_image( - 'devuan-jessie', filename='devuan-jessie.qcow2', wait=True) - - # Find a flavor with at least 512M of RAM - flavor = cloud.get_flavor_by_ram(512) - - # Boot a server, wait for it to boot, and then do whatever is needed - # to get a public ip for it. - cloud.create_server( - 'my-server', image=image, flavor=flavor, wait=True, auto_ip=True) - -Step By Step -============ - -Import the library -================== - -.. code:: python - - from openstack import cloud as openstack - -Logging -======= - -* `openstacksdk` uses standard python logging -* ``openstack.enable_logging`` does easy defaults -* Squelches some meaningless warnings - - * `debug` - - * Logs shade loggers at debug level - - * `http_debug` Implies `debug`, turns on HTTP tracing - -.. code:: python - - # Initialize and turn on debug logging - openstack.enable_logging(debug=True) - -Example with Debug Logging -========================== - -* doc/source/examples/debug-logging.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging(debug=True) - - cloud = openstack.connect( - cloud='my-vexxhost', region_name='ca-ymq-1') - cloud.get_image('Ubuntu 16.04.1 LTS [2017-03-03]') - -Example with HTTP Debug Logging -=============================== - -* doc/source/examples/http-debug-logging.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging(http_debug=True) - - cloud = openstack.connect( - cloud='my-vexxhost', region_name='ca-ymq-1') - cloud.get_image('Ubuntu 16.04.1 LTS [2017-03-03]') - -Cloud Regions -============= - -* `cloud` constructor needs `cloud` and `region_name` -* `openstack.connect` is a helper factory function - -.. code:: python - - for cloud_name, region_name in [ - ('my-vexxhost', 'ca-ymq-1'), - ('my-citycloud', 'Buf1'), - ('my-internap', 'ams01')]: - # Initialize cloud - cloud = openstack.connect(cloud=cloud_name, region_name=region_name) - -Upload an Image -=============== - -* Picks the correct upload mechanism -* **SUGGESTION** Always upload your own base images - -.. code:: python - - # Upload an image to the cloud - image = cloud.create_image( - 'devuan-jessie', filename='devuan-jessie.qcow2', wait=True) - -Always Upload an Image -====================== - -Ok. You don't have to. But, for multi-cloud... - -* Images with same content are named different on different clouds -* Images with same name on different clouds can have different content -* Upload your own to all clouds, both problems go away -* Download from OS vendor or build with `diskimage-builder` - -Find a flavor -============= - -* Flavors are all named differently on clouds -* Flavors can be found via RAM -* `get_flavor_by_ram` finds the smallest matching flavor - -.. code:: python - - # Find a flavor with at least 512M of RAM - flavor = cloud.get_flavor_by_ram(512) - -Create a server -=============== - -* my-vexxhost - - * Boot server - * Wait for `status==ACTIVE` - -* my-internap - - * Boot server on network `inap-17037-WAN1654` - * Wait for `status==ACTIVE` - -* my-citycloud - - * Boot server - * Wait for `status==ACTIVE` - * Find the `port` for the `fixed_ip` for `server` - * Create `floating-ip` on that `port` - * Wait for `floating-ip` to attach - -.. code:: python - - # Boot a server, wait for it to boot, and then do whatever is needed - # to get a public ip for it. - cloud.create_server( - 'my-server', image=image, flavor=flavor, wait=True, auto_ip=True) - -Wow. We didn't even deploy Wordpress! -===================================== - -Image and Flavor by Name or ID -============================== - -* Pass string to image/flavor -* Image/Flavor will be found by name or ID -* Common pattern -* doc/source/examples/create-server-name-or-id.py - -.. code:: python - - from openstack import cloud as openstack - - # Initialize and turn on debug logging - openstack.enable_logging(debug=True) - - for cloud_name, region_name, image, flavor in [ - ('my-vexxhost', 'ca-ymq-1', - 'Ubuntu 16.04.1 LTS [2017-03-03]', 'v1-standard-4'), - ('my-citycloud', 'Buf1', - 'Ubuntu 16.04 Xenial Xerus', '4C-4GB-100GB'), - ('my-internap', 'ams01', - 'Ubuntu 16.04 LTS (Xenial Xerus)', 'A1.4')]: - # Initialize cloud - cloud = openstack.connect(cloud=cloud_name, region_name=region_name) - - # Boot a server, wait for it to boot, and then do whatever is needed - # to get a public ip for it. - server = cloud.create_server( - 'my-server', image=image, flavor=flavor, wait=True, auto_ip=True) - print(server.name) - print(server['name']) - cloud.pprint(server) - # Delete it - this is a demo - cloud.delete_server(server, wait=True, delete_ips=True) - -cloud.pprint method was just added this morning -=============================================== - -Delete Servers -============== - -* `delete_ips` Delete any `floating_ips` the server may have - -.. code:: python - - cloud.delete_server('my-server', wait=True, delete_ips=True) - -Image and Flavor by Dict -======================== - -* Pass dict to image/flavor -* If you know if the value is Name or ID -* Common pattern -* doc/source/examples/create-server-dict.py - -.. code:: python - - from openstack import cloud as openstack - - # Initialize and turn on debug logging - openstack.enable_logging(debug=True) - - for cloud_name, region_name, image, flavor_id in [ - ('my-vexxhost', 'ca-ymq-1', 'Ubuntu 16.04.1 LTS [2017-03-03]', - '5cf64088-893b-46b5-9bb1-ee020277635d'), - ('my-citycloud', 'Buf1', 'Ubuntu 16.04 Xenial Xerus', - '0dab10b5-42a2-438e-be7b-505741a7ffcc'), - ('my-internap', 'ams01', 'Ubuntu 16.04 LTS (Xenial Xerus)', - 'A1.4')]: - # Initialize cloud - cloud = openstack.connect(cloud=cloud_name, region_name=region_name) - - # Boot a server, wait for it to boot, and then do whatever is needed - # to get a public ip for it. - server = cloud.create_server( - 'my-server', image=image, flavor=dict(id=flavor_id), - wait=True, auto_ip=True) - # Delete it - this is a demo - cloud.delete_server(server, wait=True, delete_ips=True) - -Munch Objects -============= - -* Behave like a dict and an object -* doc/source/examples/munch-dict-object.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging(debug=True) - - cloud = openstack.connect(cloud='zetta', region_name='no-osl1') - image = cloud.get_image('Ubuntu 14.04 (AMD64) [Local Storage]') - print(image.name) - print(image['name']) - -API Organized by Logical Resource -================================= - -* list_servers -* search_servers -* get_server -* create_server -* delete_server -* update_server - -For other things, it's still {verb}_{noun} - -* attach_volume -* wait_for_server -* add_auto_ip - -Cleanup Script -============== - -* Sometimes my examples had bugs -* doc/source/examples/cleanup-servers.py - -.. code:: python - - from openstack import cloud as openstack - - # Initialize and turn on debug logging - openstack.enable_logging(debug=True) - - for cloud_name, region_name in [ - ('my-vexxhost', 'ca-ymq-1'), - ('my-citycloud', 'Buf1'), - ('my-internap', 'ams01')]: - # Initialize cloud - cloud = openstack.connect(cloud=cloud_name, region_name=region_name) - for server in cloud.search_servers('my-server'): - cloud.delete_server(server, wait=True, delete_ips=True) - -Normalization -============= - -* https://docs.openstack.org/shade/latest/user/model.html#image -* doc/source/examples/normalization.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging() - - cloud = openstack.connect(cloud='fuga', region_name='cystack') - image = cloud.get_image( - 'Ubuntu 16.04 LTS - Xenial Xerus - 64-bit - Fuga Cloud Based Image') - cloud.pprint(image) - -Strict Normalized Results -========================= - -* Return only the declared model -* doc/source/examples/strict-mode.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging() - - cloud = openstack.connect( - cloud='fuga', region_name='cystack', strict=True) - image = cloud.get_image( - 'Ubuntu 16.04 LTS - Xenial Xerus - 64-bit - Fuga Cloud Based Image') - cloud.pprint(image) - -How Did I Find the Image Name for the Last Example? -=================================================== - -* I often make stupid little utility scripts -* doc/source/examples/find-an-image.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging() - - cloud = openstack.connect(cloud='fuga', region_name='cystack') - cloud.pprint([ - image for image in cloud.list_images() - if 'ubuntu' in image.name.lower()]) - -Added / Modified Information -============================ - -* Servers need more extra help -* Fetch addresses dict from neutron -* Figure out which IPs are good -* `detailed` - defaults to True, add everything -* `bare` - no extra calls - don't even fix broken things -* `bare` is still normalized -* doc/source/examples/server-information.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging(debug=True) - - cloud = openstack.connect(cloud='my-citycloud', region_name='Buf1') - try: - server = cloud.create_server( - 'my-server', image='Ubuntu 16.04 Xenial Xerus', - flavor=dict(id='0dab10b5-42a2-438e-be7b-505741a7ffcc'), - wait=True, auto_ip=True) - - print("\n\nFull Server\n\n") - cloud.pprint(server) - - print("\n\nTurn Detailed Off\n\n") - cloud.pprint(cloud.get_server('my-server', detailed=False)) - - print("\n\nBare Server\n\n") - cloud.pprint(cloud.get_server('my-server', bare=True)) - - finally: - # Delete it - this is a demo - cloud.delete_server(server, wait=True, delete_ips=True) - -Exceptions -========== - -* All shade exceptions are subclasses of `OpenStackCloudException` -* Direct REST calls throw `OpenStackCloudHTTPError` -* `OpenStackCloudHTTPError` subclasses `OpenStackCloudException` - and `requests.exceptions.HTTPError` -* `OpenStackCloudURINotFound` for 404 -* `OpenStackCloudBadRequest` for 400 - -User Agent Info -=============== - -* Set `app_name` and `app_version` for User Agents -* (sssh ... `region_name` is optional if the cloud has one region) -* doc/source/examples/user-agent.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging(http_debug=True) - - cloud = openstack.connect( - cloud='datacentred', app_name='AmazingApp', app_version='1.0') - cloud.list_networks() - -Uploading Large Objects -======================= - -* swift has a maximum object size -* Large Objects are uploaded specially -* shade figures this out and does it -* multi-threaded -* doc/source/examples/upload-object.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging(debug=True) - - cloud = openstack.connect(cloud='ovh', region_name='SBG1') - cloud.create_object( - container='my-container', name='my-object', - filename='/home/mordred/briarcliff.sh3d') - cloud.delete_object('my-container', 'my-object') - cloud.delete_container('my-container') - -Uploading Large Objects -======================= - -* Default max_file_size is 5G -* This is a conference demo -* Let's force a segment_size -* One MILLION bytes -* doc/source/examples/upload-object.py - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging(debug=True) - - cloud = openstack.connect(cloud='ovh', region_name='SBG1') - cloud.create_object( - container='my-container', name='my-object', - filename='/home/mordred/briarcliff.sh3d', - segment_size=1000000) - cloud.delete_object('my-container', 'my-object') - cloud.delete_container('my-container') - -Service Conditionals -==================== - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging(debug=True) - - cloud = openstack.connect(cloud='kiss', region_name='region1') - print(cloud.has_service('network')) - print(cloud.has_service('container-orchestration')) - -Service Conditional Overrides -============================= - -* Sometimes clouds are weird and figuring that out won't work - -.. code:: python - - from openstack import cloud as openstack - openstack.enable_logging(debug=True) - - cloud = openstack.connect(cloud='rax', region_name='DFW') - print(cloud.has_service('network')) - -.. code:: yaml - - clouds: - rax: - profile: rackspace - auth: - username: mordred - project_id: 245018 - # This is already in profile: rackspace - has_network: false - -Coming Soon -=========== - -* Completion of RESTification -* Full version discovery support -* Multi-cloud facade layer -* Microversion support (talk tomorrow) -* Completion of caching tier (talk tomorrow) -* All of you helping hacking on shade!!! (we're friendly) diff --git a/doc/source/user/resource.rst b/doc/source/user/resource.rst deleted file mode 100644 index 8453265f5..000000000 --- a/doc/source/user/resource.rst +++ /dev/null @@ -1,26 +0,0 @@ -**Note: This class is in the process of being applied as the new base class -for resources around the OpenStack SDK. Once that has been completed, -this module will be drop the 2 suffix and be the only resource module.** - -Resource -======== -.. automodule:: openstack.resource - -Components ----------- - -.. autoclass:: openstack.resource.Body - :members: - -.. autoclass:: openstack.resource.Header - :members: - -.. autoclass:: openstack.resource.URI - :members: - -The Resource class ------------------- - -.. autoclass:: openstack.resource.Resource - :members: - :member-order: bysource diff --git a/doc/source/user/resources/anti_ddos/index.rst b/doc/source/user/resources/anti_ddos/index.rst deleted file mode 100644 index dde392f6b..000000000 --- a/doc/source/user/resources/anti_ddos/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Anti DDoS Resources -=================== - -.. toctree:: - :maxdepth: 1 - - v1/config - v1/floating_ip - v1/status diff --git a/doc/source/user/resources/anti_ddos/v1/config.rst b/doc/source/user/resources/anti_ddos/v1/config.rst deleted file mode 100644 index f8d7a088b..000000000 --- a/doc/source/user/resources/anti_ddos/v1/config.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.anti_ddos.v1.config -===================================== - -.. automodule:: otcextensions.sdk.anti_ddos.v1.config - -The Anti DDoS Config Class --------------------------- - -The ``Config`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.anti_ddos.v1.config.Config - :members: diff --git a/doc/source/user/resources/anti_ddos/v1/floating_ip.rst b/doc/source/user/resources/anti_ddos/v1/floating_ip.rst deleted file mode 100644 index dd5232b81..000000000 --- a/doc/source/user/resources/anti_ddos/v1/floating_ip.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.anti_ddos.v1.floating_ip -========================================== - -.. automodule:: otcextensions.sdk.anti_ddos.v1.floating_ip - -The Anti_DDoS FloatingIP Class ------------------------------- - -The ``FloatingIP`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.anti_ddos.v1.floating_ip.FloatingIP - :members: diff --git a/doc/source/user/resources/anti_ddos/v1/status.rst b/doc/source/user/resources/anti_ddos/v1/status.rst deleted file mode 100644 index 604d46164..000000000 --- a/doc/source/user/resources/anti_ddos/v1/status.rst +++ /dev/null @@ -1,58 +0,0 @@ -otcextensions.sdk.anti_ddos.v1.status -===================================== - -.. automodule:: otcextensions.sdk.anti_ddos.v1.status - -The Anti DDoS TaskStatus Class ------------------------------- - -The ``TaskStatus`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.anti_ddos.v1.status.TaskStatus - :members: - -The Anti DDoS FloatingIPStatus Class ------------------------------------- - -The ``FloatingIPStatus`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.anti_ddos.v1.status.FloatingIPStatus - :members: - -The Anti DDoS FloatingIPEvent Class ------------------------------------ - -The ``FloatingIPEvent`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.anti_ddos.v1.status.FloatingIPEvent - :members: - -The Anti DDoS FloatingIPDayStat Class -------------------------------------- - -The ``FloatingIPDayStat`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.anti_ddos.v1.status.FloatingIPDayStat - :members: - -The Anti DDoS FloatingIPWeekStatData Class ------------------------------------------- - -The ``FloatingIPWeekStatData`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.anti_ddos.v1.status.FloatingIPWeekStatData - :members: - -The Anti DDoS FloatingIPWeekStat Class --------------------------------------- - -The ``FloatingIPWeekStat`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.anti_ddos.v1.status.FloatingIPWeekStat - :members: diff --git a/doc/source/user/resources/auto_scaling/index.rst b/doc/source/user/resources/auto_scaling/index.rst deleted file mode 100644 index daf76787a..000000000 --- a/doc/source/user/resources/auto_scaling/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -AutoScaling Resources -===================== - -.. toctree:: - :maxdepth: 1 - - v1/group - v1/config - v1/policy - v1/instance - v1/quota - v1/activity diff --git a/doc/source/user/resources/auto_scaling/v1/activity.rst b/doc/source/user/resources/auto_scaling/v1/activity.rst deleted file mode 100644 index a645657f7..000000000 --- a/doc/source/user/resources/auto_scaling/v1/activity.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.auto_scaling.v1.activity -========================================== - -.. automodule:: otcextensions.sdk.auto_scaling.v1.activity - -The AS Activity Class ---------------------- - -The ``Activity`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.auto_scaling.v1.activity.Activity - :members: diff --git a/doc/source/user/resources/auto_scaling/v1/config.rst b/doc/source/user/resources/auto_scaling/v1/config.rst deleted file mode 100644 index 292e7d531..000000000 --- a/doc/source/user/resources/auto_scaling/v1/config.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.auto_scaling.v1.config -======================================== - -.. automodule:: otcextensions.sdk.auto_scaling.v1.config - -The AS Configuration Class --------------------------- - -The ``Config`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.auto_scaling.v1.config.Config - :members: diff --git a/doc/source/user/resources/auto_scaling/v1/group.rst b/doc/source/user/resources/auto_scaling/v1/group.rst deleted file mode 100644 index 8a9563f97..000000000 --- a/doc/source/user/resources/auto_scaling/v1/group.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.auto_scaling.v1.group -======================================= - -.. automodule:: otcextensions.sdk.auto_scaling.v1.group - -The AS Group Class ------------------- - -The ``Group`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.auto_scaling.v1.group.Group - :members: diff --git a/doc/source/user/resources/auto_scaling/v1/instance.rst b/doc/source/user/resources/auto_scaling/v1/instance.rst deleted file mode 100644 index 9f31ada62..000000000 --- a/doc/source/user/resources/auto_scaling/v1/instance.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.auto_scaling.v1.instance -========================================== - -.. automodule:: otcextensions.sdk.auto_scaling.v1.instance - -The AS Instance Class ---------------------- - -The ``Instance`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.auto_scaling.v1.instance.Instance - :members: diff --git a/doc/source/user/resources/auto_scaling/v1/policy.rst b/doc/source/user/resources/auto_scaling/v1/policy.rst deleted file mode 100644 index f14861719..000000000 --- a/doc/source/user/resources/auto_scaling/v1/policy.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.auto_scaling.v1.policy -======================================== - -.. automodule:: otcextensions.sdk.auto_scaling.v1.policy - -The AS Policy Class -------------------- - -The ``Policy`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.auto_scaling.v1.policy.Policy - :members: diff --git a/doc/source/user/resources/auto_scaling/v1/quota.rst b/doc/source/user/resources/auto_scaling/v1/quota.rst deleted file mode 100644 index 3dc77141f..000000000 --- a/doc/source/user/resources/auto_scaling/v1/quota.rst +++ /dev/null @@ -1,22 +0,0 @@ -otcextensions.sdk.auto_scaling.v1.quota -======================================= - -.. automodule:: otcextensions.sdk.auto_scaling.v1.quota - -The AS Quota Class ---------------------- - -The ``Quota`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.auto_scaling.v1.quota.Quota - :members: - -The AS Scaling Quota Class --------------------------- - -The ``Quota`` class inherits from -:class:`~otcextensions.sdk.auto_scaling.v1.quota.Quota`. - -.. autoclass:: otcextensions.sdk.auto_scaling.v1.quota.ScalingQuota - :members: diff --git a/doc/source/user/resources/cce/index.rst b/doc/source/user/resources/cce/index.rst deleted file mode 100644 index 5b4e81b77..000000000 --- a/doc/source/user/resources/cce/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -AutoScaling Resources -===================== - -.. toctree:: - :maxdepth: 1 - - v1/cluster - v1/cluster_node - v3/cluster - v3/cluster_node diff --git a/doc/source/user/resources/cce/v1/cluster.rst b/doc/source/user/resources/cce/v1/cluster.rst deleted file mode 100644 index 4f61886d2..000000000 --- a/doc/source/user/resources/cce/v1/cluster.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.cce.v1.cluster -================================ - -.. automodule:: otcextensions.sdk.cce.v1.cluster - -The CCE Cluster Class ---------------------- - -The ``Cluster`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.cce.v1.cluster.Cluster - :members: diff --git a/doc/source/user/resources/cce/v1/cluster_node.rst b/doc/source/user/resources/cce/v1/cluster_node.rst deleted file mode 100644 index b6c9bf031..000000000 --- a/doc/source/user/resources/cce/v1/cluster_node.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.cce.v1.cluster_node -===================================== - -.. automodule:: otcextensions.sdk.cce.v1.cluster_node - -The CCE Cluster Host (Node) Class ---------------------------------- - -The ``ClusterHost`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.cce.v1.cluster_node.ClusterNode - :members: diff --git a/doc/source/user/resources/cce/v3/cluster.rst b/doc/source/user/resources/cce/v3/cluster.rst deleted file mode 100644 index 8b4cd7f60..000000000 --- a/doc/source/user/resources/cce/v3/cluster.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.cce.v3.cluster -================================ - -.. automodule:: otcextensions.sdk.cce.v3.cluster - -The CCE Cluster Class ---------------------- - -The ``Cluster`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.cce.v3.cluster.Cluster - :members: diff --git a/doc/source/user/resources/cce/v3/cluster_node.rst b/doc/source/user/resources/cce/v3/cluster_node.rst deleted file mode 100644 index 028332188..000000000 --- a/doc/source/user/resources/cce/v3/cluster_node.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.cce.v3.cluster_node -===================================== - -.. automodule:: otcextensions.sdk.cce.v3.cluster_node - -The CCE Cluster Host (Node) Class ---------------------------------- - -The ``ClusterHost`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.cce.v3.cluster_node.ClusterNode - :members: diff --git a/doc/source/user/resources/cts/index.rst b/doc/source/user/resources/cts/index.rst deleted file mode 100644 index c4af68b3d..000000000 --- a/doc/source/user/resources/cts/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -CTS Resources -============= - -.. toctree:: - :maxdepth: 1 - - v1/trace - v1/tracker diff --git a/doc/source/user/resources/cts/v1/trace.rst b/doc/source/user/resources/cts/v1/trace.rst deleted file mode 100644 index 04fff3d09..000000000 --- a/doc/source/user/resources/cts/v1/trace.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.cts.v1.trace -============================== - -.. automodule:: otcextensions.sdk.cts.v1.trace - -The CTS Trace Class -------------------- - -The ``Trace`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.cts.v1.trace.Trace - :members: diff --git a/doc/source/user/resources/cts/v1/tracker.rst b/doc/source/user/resources/cts/v1/tracker.rst deleted file mode 100644 index c3ace1804..000000000 --- a/doc/source/user/resources/cts/v1/tracker.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.cts.v1.tracker -================================ - -.. automodule:: otcextensions.sdk.cts.v1.tracker - -The CTS Tracker Class ---------------------- - -The ``Tracker`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.cts.v1.tracker.Tracker - :members: diff --git a/doc/source/user/resources/dcs/index.rst b/doc/source/user/resources/dcs/index.rst deleted file mode 100644 index f2c49c26d..000000000 --- a/doc/source/user/resources/dcs/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -DCS Resources -============= - -.. toctree:: - :maxdepth: 1 - - v1/backup - v1/config - v1/instance - v1/restore - v1/statistic diff --git a/doc/source/user/resources/dcs/v1/backup.rst b/doc/source/user/resources/dcs/v1/backup.rst deleted file mode 100644 index 243b376eb..000000000 --- a/doc/source/user/resources/dcs/v1/backup.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.backup -================================= - -.. automodule:: otcextensions.sdk.dcs.v1.backup - -The DCS Backup Class --------------------- - -The ``Backup`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dcs.v1.backup.Backup - :members: diff --git a/doc/source/user/resources/dcs/v1/config.rst b/doc/source/user/resources/dcs/v1/config.rst deleted file mode 100644 index 78656037e..000000000 --- a/doc/source/user/resources/dcs/v1/config.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.config -================================= - -.. automodule:: otcextensions.sdk.dcs.v1.config - -The DCS Config Class --------------------- - -The ``Config`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dcs.v1.config.Config - :members: diff --git a/doc/source/user/resources/dcs/v1/instance.rst b/doc/source/user/resources/dcs/v1/instance.rst deleted file mode 100644 index 1df70cb93..000000000 --- a/doc/source/user/resources/dcs/v1/instance.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.instance -================================= - -.. automodule:: otcextensions.sdk.dcs.v1.instance - -The DCS Instance Class ----------------------- - -The ``Instance`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dcs.v1.instance.Instance - :members: diff --git a/doc/source/user/resources/dcs/v1/restore.rst b/doc/source/user/resources/dcs/v1/restore.rst deleted file mode 100644 index 16a23a582..000000000 --- a/doc/source/user/resources/dcs/v1/restore.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.restore -================================= - -.. automodule:: otcextensions.sdk.dcs.v1.restore - -The DCS Restore Class ---------------------- - -The ``Restore`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dcs.v1.restore.Restore - :members: diff --git a/doc/source/user/resources/dcs/v1/statistic.rst b/doc/source/user/resources/dcs/v1/statistic.rst deleted file mode 100644 index 53b06a053..000000000 --- a/doc/source/user/resources/dcs/v1/statistic.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.statistic -================================== - -.. automodule:: otcextensions.sdk.dcs.v1.statistic - -The DCS Statistic Class ------------------------ - -The ``Statistic`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dcs.v1.statistic.Statistic - :members: diff --git a/doc/source/user/resources/deh/index.rst b/doc/source/user/resources/deh/index.rst deleted file mode 100644 index d3b3d1e7e..000000000 --- a/doc/source/user/resources/deh/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -DeH Resources -============= - -.. toctree:: - :maxdepth: 1 - - v1/host - v1/host_type - v1/server diff --git a/doc/source/user/resources/deh/v1/host.rst b/doc/source/user/resources/deh/v1/host.rst deleted file mode 100644 index 2b9942dcc..000000000 --- a/doc/source/user/resources/deh/v1/host.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.deh.v1.host -============================= - -.. automodule:: otcextensions.sdk.deh.v1.host - -The DeH Host Class ------------------- - -The ``Host`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.deh.v1.host.Host - :members: diff --git a/doc/source/user/resources/deh/v1/host_type.rst b/doc/source/user/resources/deh/v1/host_type.rst deleted file mode 100644 index 1d06abd4d..000000000 --- a/doc/source/user/resources/deh/v1/host_type.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.deh.v1.host_type -================================== - -.. automodule:: otcextensions.sdk.deh.v1.host_type - -The DeH Host Type Class ------------------------ - -The ``HostType`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.deh.v1.host_type.HostType - :members: diff --git a/doc/source/user/resources/deh/v1/server.rst b/doc/source/user/resources/deh/v1/server.rst deleted file mode 100644 index 25d80def7..000000000 --- a/doc/source/user/resources/deh/v1/server.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.deh.v1.server -=============================== - -.. automodule:: otcextensions.sdk.deh.v1.server - -The DeH Server Class --------------------- - -The ``Server`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.deh.v1.server.Server - :members: diff --git a/doc/source/user/resources/dms/index.rst b/doc/source/user/resources/dms/index.rst deleted file mode 100644 index 210555c88..000000000 --- a/doc/source/user/resources/dms/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -DMS Resources -============= - -.. toctree:: - :maxdepth: 1 - - v1/group - v1/group_message - v1/message - v1/queue - v1/quota diff --git a/doc/source/user/resources/dms/v1/group.rst b/doc/source/user/resources/dms/v1/group.rst deleted file mode 100644 index 03663435e..000000000 --- a/doc/source/user/resources/dms/v1/group.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.group -============================== - -.. automodule:: otcextensions.sdk.dms.v1.group - -The DMS Group Class -------------------- - -The ``Group`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dms.v1.group.Group - :members: diff --git a/doc/source/user/resources/dms/v1/group_message.rst b/doc/source/user/resources/dms/v1/group_message.rst deleted file mode 100644 index 94090ce49..000000000 --- a/doc/source/user/resources/dms/v1/group_message.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.group_message -====================================== - -.. automodule:: otcextensions.sdk.dms.v1.group_message - -The DMS GroupMessage Class --------------------------- - -The ``GroupMessage`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dms.v1.group_message.GroupMessage - :members: diff --git a/doc/source/user/resources/dms/v1/message.rst b/doc/source/user/resources/dms/v1/message.rst deleted file mode 100644 index 72360e7f5..000000000 --- a/doc/source/user/resources/dms/v1/message.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.message -================================ - -.. automodule:: otcextensions.sdk.dms.v1.message - -The DMS Message Class ---------------------- - -The ``Message`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dms.v1.message.Message - :members: diff --git a/doc/source/user/resources/dms/v1/queue.rst b/doc/source/user/resources/dms/v1/queue.rst deleted file mode 100644 index 1942b9e68..000000000 --- a/doc/source/user/resources/dms/v1/queue.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.queue -============================== - -.. automodule:: otcextensions.sdk.dms.v1.queue - -The DMS Queue Class -------------------- - -The ``Queue`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dms.v1.queue.Queue - :members: diff --git a/doc/source/user/resources/dms/v1/quota.rst b/doc/source/user/resources/dms/v1/quota.rst deleted file mode 100644 index 5faa27fd5..000000000 --- a/doc/source/user/resources/dms/v1/quota.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dcs.v1.quota -============================== - -.. automodule:: otcextensions.sdk.dms.v1.quota - -The DMS Quota Class -------------------- - -The ``Quota`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dms.v1.quota.Quota - :members: diff --git a/doc/source/user/resources/dns/index.rst b/doc/source/user/resources/dns/index.rst deleted file mode 100644 index beb9d656b..000000000 --- a/doc/source/user/resources/dns/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Anti DDoS Resources -=================== - -.. toctree:: - :maxdepth: 1 - - v2/zone - v2/nameserver - v2/floating_ip - v2/recordset diff --git a/doc/source/user/resources/dns/v2/floating_ip.rst b/doc/source/user/resources/dns/v2/floating_ip.rst deleted file mode 100644 index 6b8b91b83..000000000 --- a/doc/source/user/resources/dns/v2/floating_ip.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dns.v2.floating_ip -==================================== - -.. automodule:: otcextensions.sdk.dns.v2.floating_ip - -The DNS FloatingIP Class ------------------------- - -The ``floating_ip`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dns.v2.floating_ip.FloatingIP - :members: diff --git a/doc/source/user/resources/dns/v2/nameserver.rst b/doc/source/user/resources/dns/v2/nameserver.rst deleted file mode 100644 index 16bc1bc38..000000000 --- a/doc/source/user/resources/dns/v2/nameserver.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dns.v2.nameserver -=================================== - -.. automodule:: otcextensions.sdk.dns.v2.nameserver - -The DNS Nameserver Class ------------------------- - -The ``Nameserver`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dns.v2.nameserver.NameServer - :members: diff --git a/doc/source/user/resources/dns/v2/recordset.rst b/doc/source/user/resources/dns/v2/recordset.rst deleted file mode 100644 index b96c4f748..000000000 --- a/doc/source/user/resources/dns/v2/recordset.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dns.v2.recordset -================================== - -.. automodule:: otcextensions.sdk.dns.v2.recordset - -The DNS Recordset Class ------------------------ - -The ``recordset`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dns.v2.recordset.Recordset - :members: diff --git a/doc/source/user/resources/dns/v2/zone.rst b/doc/source/user/resources/dns/v2/zone.rst deleted file mode 100644 index d0afbbc10..000000000 --- a/doc/source/user/resources/dns/v2/zone.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.dns.v2.zone -============================= - -.. automodule:: otcextensions.sdk.dns.v2.zone - -The DNS Zone Class ------------------- - -The ``Zone`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.dns.v2.zone.Zone - :members: diff --git a/doc/source/user/resources/kms/index.rst b/doc/source/user/resources/kms/index.rst deleted file mode 100644 index f1bc1afe8..000000000 --- a/doc/source/user/resources/kms/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -AutoScaling Resources -===================== - -.. toctree:: - :maxdepth: 1 - - v1/key - v1/data_key diff --git a/doc/source/user/resources/kms/v1/data_key.rst b/doc/source/user/resources/kms/v1/data_key.rst deleted file mode 100644 index 24a417254..000000000 --- a/doc/source/user/resources/kms/v1/data_key.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.kms.v1.data_key -================================= - -.. automodule:: otcextensions.sdk.kms.v1.data_key - -The KMS DEK Class ------------------ - -The ``DataKey`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.kms.v1.data_key.DataKey - :members: diff --git a/doc/source/user/resources/kms/v1/key.rst b/doc/source/user/resources/kms/v1/key.rst deleted file mode 100644 index 0f37920f3..000000000 --- a/doc/source/user/resources/kms/v1/key.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.kms.v1.key -============================ - -.. automodule:: otcextensions.sdk.kms.v1.key - -The KMS CMK Class ------------------ - -The ``Key`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.kms.v1.key.Key - :members: diff --git a/doc/source/user/resources/obs/index.rst b/doc/source/user/resources/obs/index.rst deleted file mode 100644 index adea4ca5d..000000000 --- a/doc/source/user/resources/obs/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -OBS Resources -============= - -.. toctree:: - :maxdepth: 1 - - v1/container - v1/obj diff --git a/doc/source/user/resources/obs/v1/container.rst b/doc/source/user/resources/obs/v1/container.rst deleted file mode 100644 index 658398031..000000000 --- a/doc/source/user/resources/obs/v1/container.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.obs.v1.container -================================== - -.. automodule:: otcextensions.sdk.obs.v1.container - -The OBS Container (Bucket) Class --------------------------------- - -The ``Container`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.obs.v1.container.Container - :members: diff --git a/doc/source/user/resources/obs/v1/obj.rst b/doc/source/user/resources/obs/v1/obj.rst deleted file mode 100644 index 5492cdbf8..000000000 --- a/doc/source/user/resources/obs/v1/obj.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.obs.v1.obj -============================ - -.. automodule:: otcextensions.sdk.obs.v1.obj - -The OBS Object Class --------------------- - -The ``Object`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.obs.v1.obj.Object - :members: diff --git a/doc/source/user/resources/rds/index.rst b/doc/source/user/resources/rds/index.rst deleted file mode 100644 index 935c168e6..000000000 --- a/doc/source/user/resources/rds/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -RDS Resources -============= - -.. toctree:: - :maxdepth: 1 - - v1/configuration - v1/flavor - v1/instance - v3/configuration - v3/flavor - v3/instance diff --git a/doc/source/user/resources/rds/v1/configuration.rst b/doc/source/user/resources/rds/v1/configuration.rst deleted file mode 100644 index 2fe69c1b5..000000000 --- a/doc/source/user/resources/rds/v1/configuration.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.rds.v1.configuration -====================================== - -.. automodule:: otcextensions.sdk.rds.v1.configuration - -The Configuration Class ------------------------ - -The ``Configuration`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.rds.v1.configuration.ConfigurationGroup - :members: diff --git a/doc/source/user/resources/rds/v1/flavor.rst b/doc/source/user/resources/rds/v1/flavor.rst deleted file mode 100644 index 2033f62eb..000000000 --- a/doc/source/user/resources/rds/v1/flavor.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.rds.v1.flavor -=============================== - -.. automodule:: otcextensions.sdk.rds.v1.flavor - -The Flavor Class ----------------- - -The ``Flavor`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.rds.v1.flavor.Flavor - :members: diff --git a/doc/source/user/resources/rds/v1/instance.rst b/doc/source/user/resources/rds/v1/instance.rst deleted file mode 100644 index 07e75ff44..000000000 --- a/doc/source/user/resources/rds/v1/instance.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.rds.v1.instance -================================= - -.. automodule:: otcextensions.sdk.rds.v1.instance - -The Instance Class ------------------- - -The ``Instance`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.rds.v1.instance.Instance - :members: diff --git a/doc/source/user/resources/rds/v3/configuration.rst b/doc/source/user/resources/rds/v3/configuration.rst deleted file mode 100644 index a6b436702..000000000 --- a/doc/source/user/resources/rds/v3/configuration.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.rds.v3.configuration -====================================== - -.. automodule:: otcextensions.sdk.rds.v3.configuration - -The Configuration Class ------------------------ - -The ``Configuration`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.rds.v3.configuration.Configuration - :members: diff --git a/doc/source/user/resources/rds/v3/flavor.rst b/doc/source/user/resources/rds/v3/flavor.rst deleted file mode 100644 index a8806f213..000000000 --- a/doc/source/user/resources/rds/v3/flavor.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.rds.v3.flavor -=============================== - -.. automodule:: otcextensions.sdk.rds.v3.flavor - -The Flavor Class ----------------- - -The ``Flavor`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.rds.v3.flavor.Flavor - :members: diff --git a/doc/source/user/resources/rds/v3/instance.rst b/doc/source/user/resources/rds/v3/instance.rst deleted file mode 100644 index d72e7cd4f..000000000 --- a/doc/source/user/resources/rds/v3/instance.rst +++ /dev/null @@ -1,13 +0,0 @@ -otcextensions.sdk.rds.v3.instance -================================= - -.. automodule:: otcextensions.sdk.rds.v3.instance - -The Instance Class ------------------- - -The ``Instance`` class inherits from -:class:`~otcextensions.sdk.sdk_resource.Resource`. - -.. autoclass:: otcextensions.sdk.rds.v3.instance.Instance - :members: diff --git a/doc/source/user/transition_from_profile.rst b/doc/source/user/transition_from_profile.rst deleted file mode 100644 index a6edc6a5e..000000000 --- a/doc/source/user/transition_from_profile.rst +++ /dev/null @@ -1,186 +0,0 @@ -Transition from Profile -======================= - -.. note:: This section describes migrating code from a previous interface of - openstacksdk and can be ignored by people writing new code. - -If you have code that currently uses the :class:`~openstack.profile.Profile` -object and/or an ``authenticator`` instance from an object based on -``openstack.auth.base.BaseAuthPlugin``, that code should be updated to use the -:class:`~openstack.config.cloud_region.CloudRegion` object instead. - -.. important:: - - :class:`~openstack.profile.Profile` is going away. Existing code using it - should be migrated as soon as possible. - -Writing Code that Works with Both ---------------------------------- - -These examples should all work with both the old and new interface, with one -caveat. With the old interface, the ``CloudConfig`` object comes from the -``os-client-config`` library, and in the new interface that has been moved -into the SDK. In order to write code that works with both the old and new -interfaces, use the following code to import the config namespace: - -.. code-block:: python - - try: - from openstack import config as occ - except ImportError: - from os_client_config import config as occ - -The examples will assume that the config module has been imported in that -manner. - -.. note:: Yes, there is an easier and less verbose way to do all of these. - These are verbose to handle both the old and new interfaces in the - same codebase. - -Replacing authenticator ------------------------ - -There is no direct replacement for ``openstack.auth.base.BaseAuthPlugin``. -``openstacksdk`` uses the `keystoneauth`_ library for authentication -and HTTP interactions. `keystoneauth`_ has `auth plugins`_ that can be used -to control how authentication is done. The ``auth_type`` config parameter -can be set to choose the correct authentication method to be used. - -Replacing Profile ------------------ - -The right way to replace the use of ``openstack.profile.Profile`` depends -a bit on what you're trying to accomplish. Common patterns are listed below, -but in general the approach is either to pass a cloud name to the -`openstack.connection.Connection` constructor, or to construct a -`openstack.config.cloud_region.CloudRegion` object and pass it to the -constructor. - -All of the examples on this page assume that you want to support old and -new interfaces simultaneously. There are easier and less verbose versions -of each that are available if you can just make a clean transition. - -Getting a Connection to a named cloud from clouds.yaml ------------------------------------------------------- - -If you want is to construct a `openstack.connection.Connection` based on -parameters configured in a ``clouds.yaml`` file, or from environment variables: - -.. code-block:: python - - import openstack.connection - - conn = connection.from_config(cloud_name='name-of-cloud-you-want') - -Getting a Connection from python arguments avoiding clouds.yaml ---------------------------------------------------------------- - -If, on the other hand, you want to construct a -`openstack.connection.Connection`, but are in a context where reading config -from a clouds.yaml file is undesirable, such as inside of a Service: - -* create a `openstack.config.loader.OpenStackConfig` object, telling - it to not load yaml files. Optionally pass an ``app_name`` and - ``app_version`` which will be added to user-agent strings. -* get a `openstack.config.cloud_region.CloudRegion` object from it -* get a `openstack.connection.Connection` - -.. code-block:: python - - try: - from openstack import config as occ - except ImportError: - from os_client_config import config as occ - from openstack import connection - - loader = occ.OpenStackConfig( - load_yaml_files=False, - app_name='spectacular-app', - app_version='1.0') - cloud_region = loader.get_one_cloud( - region_name='my-awesome-region', - auth_type='password', - auth=dict( - auth_url='https://auth.example.com', - username='amazing-user', - user_domain_name='example-domain', - project_name='astounding-project', - user_project_name='example-domain', - password='super-secret-password', - )) - conn = connection.from_config(cloud_config=cloud_region) - -.. note:: app_name and app_version are completely optional, and auth_type - defaults to 'password'. They are shown here for clarity as to - where they should go if they want to be set. - -Getting a Connection from python arguments and optionally clouds.yaml ---------------------------------------------------------------------- - -If you want to make a connection from python arguments and want to allow -one of them to optionally be ``cloud`` to allow selection of a named cloud, -it's essentially the same as the previous example, except without -``load_yaml_files=False``. - -.. code-block:: python - - try: - from openstack import config as occ - except ImportError: - from os_client_config import config as occ - from openstack import connection - - loader = occ.OpenStackConfig( - app_name='spectacular-app', - app_version='1.0') - cloud_region = loader.get_one_cloud( - region_name='my-awesome-region', - auth_type='password', - auth=dict( - auth_url='https://auth.example.com', - username='amazing-user', - user_domain_name='example-domain', - project_name='astounding-project', - user_project_name='example-domain', - password='super-secret-password', - )) - conn = connection.from_config(cloud_config=cloud_region) - -Parameters to get_one_cloud ---------------------------- - -The most important things to note are: - -* ``auth_type`` specifies which kind of authentication plugin to use. It - controls how authentication is done, as well as what parameters are required. -* ``auth`` is a dictionary containing the parameters needed by the auth plugin. - The most common information it needs are user, project, domain, auth_url - and password. -* The rest of the keyword arguments to - ``openstack.config.loader.OpenStackConfig.get_one_cloud`` are either - parameters needed by the `keystoneauth Session`_ object, which control how - HTTP connections are made, or parameters needed by the - `keystoneauth Adapter`_ object, which control how services are found in the - Keystone Catalog. - -For `keystoneauth Adapter`_ parameters, since there is one -`openstack.connection.Connection` object but many services, per-service -parameters are formed by using the official ``service_type`` of the service -in question. For instance, to override the endpoint for the ``compute`` -service, the parameter ``compute_endpoint_override`` would be used. - -``region_name`` in ``openstack.profile.Profile`` was a per-service parameter. -This is no longer a valid concept. An `openstack.connection.Connection` is a -connection to a region of a cloud. If you are in an extreme situation where -you have one service in one region and a different service in a different -region, you must use two different `openstack.connection.Connection` objects. - -.. note:: service_type, although a parameter for keystoneauth1.adapter.Adapter, - is not a valid parameter for get_one_cloud. service_type is the key - by which services are referred, so saying - 'compute_service_type="henry"' doesn't have any meaning. - -.. _keystoneauth: https://docs.openstack.org/keystoneauth/latest/ -.. _auth plugins: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html -.. _keystoneauth Adapter: https://docs.openstack.org/keystoneauth/latest/api/keystoneauth1.html#keystoneauth1.adapter.Adapter -.. _keystoneauth Session: https://docs.openstack.org/keystoneauth/latest/api/keystoneauth1.html#keystoneauth1.session.Session diff --git a/doc/source/user/utils.rst b/doc/source/user/utils.rst deleted file mode 100644 index 5c1f39de9..000000000 --- a/doc/source/user/utils.rst +++ /dev/null @@ -1,3 +0,0 @@ -Utilities -========= -.. automodule:: openstack.utils From 47ad81fea204b9806455d86c1fefa04f5d1c5a5f Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Tue, 10 Mar 2020 15:46:54 +0000 Subject: [PATCH 12/42] configuration section updated --- doc/source/install/configuration.rst | 137 +++++++++++++++++---------- 1 file changed, 88 insertions(+), 49 deletions(-) diff --git a/doc/source/install/configuration.rst b/doc/source/install/configuration.rst index bbf6326fa..a2f227f33 100644 --- a/doc/source/install/configuration.rst +++ b/doc/source/install/configuration.rst @@ -3,12 +3,12 @@ Configuration You can connect to the Open Telekom Cloud and OpenStack clouds in general using two approaches. The first one uses a credential file called -``clouds.yaml`` and the other one is to use environment variables. +``clouds.yaml`` and the other one is to use ``environment variables``. Configuring a clouds.yaml file ------------------------------ -The credential file clouds.yaml will be queried automatically in different +The credential file ``clouds.yaml`` will be queried automatically in different locations with increasing precedence: 1. system-wide (/etc/openstack/{clouds,secure}.yaml) @@ -23,21 +23,42 @@ A sample clouds.yaml file is listed below to connect with Open Telekom Cloud: clouds: otc: + profile: otc auth: - username: 'USER_NAME' - password: 'PASS' - project_name: 'eu-de' - auth_url: 'https://iam.eu-de.otc.t-systems.com:443/v3' + 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_VALUE' # AK/SK pair for access to OBS - sk: 'SK_VALUE' + ak: '' # AK/SK pair for access to OBS + sk: '' + +.. note:: + The name ``otc`` is self-defined and can be changed to any value. + +AK/SK values required for access to some services (i.e. OBS) can +be either configured as shown above in the clouds.yaml/secure.yaml, or +they can be automatically retrieved from the S3_ACCESS_KEY_ID and +S3_SECRET_ACCESS_KEY. + +Test your connection +^^^^^^^^^^^^^^^^^^^^ + +If you followed the `installation advices `_ for your specific +operating system, you can use the following command to test the basic +functionality. -The name otc is self-defined and can be changed. AK/SK values required for -access to some services (i.e. OBS) can be either configured as shown above -in the clouds.yaml/secure.yaml, or they can be automatically retrieved from -the S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY. +.. code-block:: bash + + $ openstack --os-cloud otc flavor list + + +Configuration of a Second Project +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Additional connections to other Openstack-clouds or -projects can be added to the file as shown below: @@ -47,34 +68,34 @@ to the file as shown below: .. code-block:: yaml clouds: - otc: + otcfirstproject: + profile: otc auth: - username: 'USER_NAME' - password: 'PASS' - project_name: 'eu-de' - auth_url: 'https://iam.eu-de.otc.t-systems.com:443/v3' + 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_VALUE' # AK/SK pair for access to OBS - sk: 'SK_VALUE' + ak: '' # AK/SK pair for access to OBS + sk: '' otcsecondproject: - region_name: eu-de + profile: otc auth: - username: '' - password: '' - project_id: '' - user_domain_id: '' + username: '' + password: '' + project_name: '' + # or project_id: '<123456_PROJECT_ID2>' + user_domain_name: 'OTC00000000001000000xxx' + # or user_domain_id: '<123456_DOMAIN_ID2>' auth_url: 'https://iam.eu-de.otc.t-systems.com:443/v3' - -Test your connection -^^^^^^^^^^^^^^^^^^^^ - -Use the following command to test the basic functionality. - -.. code-block:: bash - - $ openstack --os-cloud otc flavor list + interface: 'public' + identity_api_version: 3 # !Important + ak: '' # AK/SK pair for access to OBS + sk: '' Splitting the credentials in clouds.yaml and secure.yaml ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -89,15 +110,18 @@ secret which is left out from ``clouds.yaml``: clouds: otc: + profile: otc auth: - username: 'USER_NAME' - project_name: 'eu-de' - auth_url: 'https://iam.eu-de.otc.t-systems.com:443/v3' + username: '' + 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_VALUE' # AK/SK pair for access to OBS - sk: 'SK_VALUE' + ak: '' # AK/SK pair for access to OBS + sk: '' **secure.yaml** @@ -118,22 +142,37 @@ Open Telekom Cloud servers this file exists on bootup and needs to be changed according to your credentials. .. code-block:: bash + + # .ostackrc file + export OS_USERNAME="" + export OS_USER_DOMAIN_NAME= + export OS_PASSWORD= # optional + export OS_TENANT_NAME=eu-de + export OS_PROJECT_NAME= + export OS_AUTH_URL=https://iam.eu-de.otc.t-systems.com:443/v3 + export NOVA_ENDPOINT_TYPE=publicURL + export OS_ENDPOINT_TYPE=publicURL + export CINDER_ENDPOINT_TYPE=publicURL + export OS_VOLUME_API_VERSION=2 + export OS_IDENTITY_API_VERSION=3 + export OS_IMAGE_API_VERSION=2 + +Run the source command to make the ``environment variables`` available. - $ export OS_AUTH_URL= - $ export OS_IDENTITY_API_VERSION=3 - $ export OS_PROJECT_NAME= - $ export OS_PROJECT_DOMAIN_NAME= - $ export OS_USERNAME= - $ export OS_USER_DOMAIN_NAME= - $ export OS_PASSWORD= # (optional) - $ export S3_ACCESS_KEY_ID= - $ export S3_SECRET_ACCESS_KEY= +.. code-block:: bash + + $ source .ostackrc + +The ``environment variables`` are now available for usage. For testing your +connection run the following command. Test your connection ^^^^^^^^^^^^^^^^^^^^ -Use the following command to test the basic functionality. +If you followed the `installation advices `_ for your specific +operating system, you can use the following command to test the basic +functionality. .. code-block:: bash - $ openstack flavor list + $ openstack --os-cloud otc flavor list From ebd414d75e99a3145a19101582490ac32d95b5bd Mon Sep 17 00:00:00 2001 From: Nils Magnus Date: Wed, 11 Mar 2020 19:55:49 +0100 Subject: [PATCH 13/42] improve the enforcer output during tests --- doc/source/enforcer.py | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/doc/source/enforcer.py b/doc/source/enforcer.py index ca79b0311..7c6d46953 100644 --- a/doc/source/enforcer.py +++ b/doc/source/enforcer.py @@ -20,8 +20,14 @@ LOG = logging.getLogger(__name__) # NOTE: We do this because I can't find any way to pass "-v" -# into sphinx-build through pbr... -DEBUG = True if os.getenv("ENFORCER_DEBUG") else False +# into sphinx-build through pbr ... + +if os.getenv("ENFORCER_DEBUG"): + DEBUG = True + LOG.info("ENFORCER: Debugging is on.") +else: + DEBUG = False + WRITTEN_METHODS = set() @@ -116,7 +122,8 @@ def build_finished(app, exception): # We also need to deal with Proxy subclassing keystoneauth.adapter.Adapter # now - some of the warnings come from Adapter elements. for name in sorted(missing): - LOG.info("ENFORCER: %s was not included in the output" % name) + if DEBUG: + LOG.info("ENFORCER: %s was not included in the output" % name) if app.config.enforcer_warnings_as_errors and missing_count > 0: raise EnforcementError( From 1b164394f0b588dca40c3ea0db3b5a61b3a2ff1e Mon Sep 17 00:00:00 2001 From: Nils Magnus Date: Wed, 11 Mar 2020 19:58:14 +0100 Subject: [PATCH 14/42] introduce the CLI chapter --- doc/source/cli/index.rst | 49 ++++++++++++++++++++++++++++------------ 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index af93b47d5..8676a9b32 100644 --- a/doc/source/cli/index.rst +++ b/doc/source/cli/index.rst @@ -1,19 +1,38 @@ -OpenStack CLI Usage -========================= +OpenStack Client (CLI) +====================== + +The OpenStack Client is a self-contained OpenStack project providing a +command line interface to the most important cloud functions. For most +of the API calls an equivalent CLI command is available under a shared +command invoked as ``openstack``. An example is ``openstack server +list``. For reference see the documentation of the OpenStack Client +(OSC). + +The OTC Extensions don't re-implement the CLI tool, but augment it +automatically. If you have installed OTC Extensions and OpenStack +Client, the latter understands many extra commands: + +.. code-block:: bash + + openstack --help | grep -c otcextensions + 164 + +For details of the available commands, check the detailed CLI +documentation of these services: .. toctree:: :maxdepth: 1 - anti_ddos.rst - auto_scaling.rst - cce_v2.rst - cts.rst - dcs.rst - deh.rst - dms.rst - dns.rst - rds.rst - kms.rst - load_balancer.rst - obs.rst - volume_backup.rst + anti_ddos + auto_scaling + cce_v2 + cts + dcs + deh + dms + dns + kms + load_balancer + obs + rds + volume_backup From fda611f937a283098674ff63ccb5c8c84bd845a5 Mon Sep 17 00:00:00 2001 From: Nils Magnus Date: Wed, 11 Mar 2020 20:35:33 +0100 Subject: [PATCH 15/42] fix pep8 issues, mostly whitespace --- doc/source/appendices/index.rst | 20 +- doc/source/cli/index.rst | 4 +- doc/source/index.rst | 16 +- doc/source/install/configuration.rst | 356 +++++++++++------------ doc/source/install/index.rst | 5 +- doc/source/install/pip_install.rst | 350 +++++++++++----------- doc/source/install/source_install.rst | 81 +++--- doc/source/sdk/architecture.rst | 35 ++- doc/source/sdk/getting_started.rst | 127 ++++---- doc/source/sdk/guides/index.rst | 64 ++-- doc/source/sdk/index.rst | 52 ++-- doc/source/sdk/proxies/auto_scaling.rst | 9 +- doc/source/sdk/proxies/index.rst | 106 +++---- doc/source/sdk/proxies/volume_backup.rst | 10 +- otcextensions/sdk/rds/v3/_proxy.py | 2 +- 15 files changed, 621 insertions(+), 616 deletions(-) diff --git a/doc/source/appendices/index.rst b/doc/source/appendices/index.rst index 0b54d3916..c0e9836e7 100644 --- a/doc/source/appendices/index.rst +++ b/doc/source/appendices/index.rst @@ -1,10 +1,10 @@ -Appendices -========== - -.. toctree:: - :maxdepth: 1 - - releasenotes.rst - history.rst - issues.rst - glossary.rst \ No newline at end of file +Appendices +========== + +.. toctree:: + :maxdepth: 1 + + releasenotes + history + issues + glossary diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index 8676a9b32..c4d31c1f4 100644 --- a/doc/source/cli/index.rst +++ b/doc/source/cli/index.rst @@ -13,10 +13,10 @@ automatically. If you have installed OTC Extensions and OpenStack Client, the latter understands many extra commands: .. code-block:: bash - + openstack --help | grep -c otcextensions 164 - + For details of the available commands, check the detailed CLI documentation of these services: diff --git a/doc/source/index.rst b/doc/source/index.rst index a9b900285..0cb6f034b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -72,18 +72,20 @@ General Information Adding to that, there is some general background information available: -* In a :doc:`glossary ` important terms and their naming conventions are - described. +* In a :doc:`glossary ` important terms and their + naming conventions are described. -* There is a :doc:`history ` explaing the ancestry of this project. This - may or may not be insightful if you want to understand the projects - architecture. +* There is a :doc:`history ` explaing the ancestry + of this project. This may or may not be insightful if you want to + understand the projects architecture. -* There is a :doc:`release history ` available. +* There is a :doc:`release history ` + available. * A list of :doc:`issues ` is maintained. -* Currently 13 services are :doc:`covered ` by the OTC extensions. +* Currently 13 services are :doc:`covered ` by the OTC + extensions. .. _OpenStack SDK: https://docs.openstack.org/openstacksdk/ .. _OpenStack API: https://docs.openstack.org/api-quick-start/ diff --git a/doc/source/install/configuration.rst b/doc/source/install/configuration.rst index a2f227f33..86a98786a 100644 --- a/doc/source/install/configuration.rst +++ b/doc/source/install/configuration.rst @@ -1,178 +1,178 @@ -Configuration -============= - -You can connect to the Open Telekom Cloud and OpenStack clouds in general -using two approaches. The first one uses a credential file called -``clouds.yaml`` and the other one is to use ``environment variables``. - -Configuring a clouds.yaml file ------------------------------- - -The credential file ``clouds.yaml`` will be queried automatically in different -locations with increasing precedence: - -1. system-wide (/etc/openstack/{clouds,secure}.yaml) -2. Home directory / user space (~/.config/openstack/{clouds,secure}.yaml) -3. Current directory (./{clouds,secure}.yaml) - -A sample clouds.yaml file is listed below to connect with Open Telekom Cloud: - -**clouds.yaml** - -.. code-block:: yaml - - 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: '' - -.. note:: - The name ``otc`` is self-defined and can be changed to any value. - -AK/SK values required for access to some services (i.e. OBS) can -be either configured as shown above in the clouds.yaml/secure.yaml, or -they can be automatically retrieved from the S3_ACCESS_KEY_ID and -S3_SECRET_ACCESS_KEY. - -Test your connection -^^^^^^^^^^^^^^^^^^^^ - -If you followed the `installation advices `_ for your specific -operating system, you can use the following command to test the basic -functionality. - -.. code-block:: bash - - $ openstack --os-cloud otc flavor list - - -Configuration of a Second Project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Additional connections to other Openstack-clouds or -projects can be added -to the file as shown below: - -**clouds.yaml** - -.. code-block:: yaml - - clouds: - otcfirstproject: - 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: '' - otcsecondproject: - profile: otc - auth: - username: '' - password: '' - project_name: '' - # or project_id: '<123456_PROJECT_ID2>' - user_domain_name: 'OTC00000000001000000xxx' - # or user_domain_id: '<123456_DOMAIN_ID2>' - 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: '' - -Splitting the credentials in clouds.yaml and secure.yaml -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In some scenarios a split of security credentials from the configuration file -is necessary. The optional file ``secure.yaml`` can be used to store the -secret which is left out from ``clouds.yaml``: - -**clouds.yaml** - -.. code-block:: yaml - - clouds: - otc: - profile: otc - auth: - username: '' - 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: '' - -**secure.yaml** - -.. code-block:: yaml - - clouds: - otc: - auth: - password: '' - -Configuration of Environment Variables --------------------------------------- - -Instead of using the clouds.yaml file, environmnt variables can be configured -to connect to the Open Telekom Cloud. Create a simple file like ``.ostackrc`` -in the home directory and source the file to make the variables available. On -Open Telekom Cloud servers this file exists on bootup and needs to be changed -according to your credentials. - -.. code-block:: bash - - # .ostackrc file - export OS_USERNAME="" - export OS_USER_DOMAIN_NAME= - export OS_PASSWORD= # optional - export OS_TENANT_NAME=eu-de - export OS_PROJECT_NAME= - export OS_AUTH_URL=https://iam.eu-de.otc.t-systems.com:443/v3 - export NOVA_ENDPOINT_TYPE=publicURL - export OS_ENDPOINT_TYPE=publicURL - export CINDER_ENDPOINT_TYPE=publicURL - export OS_VOLUME_API_VERSION=2 - export OS_IDENTITY_API_VERSION=3 - export OS_IMAGE_API_VERSION=2 - -Run the source command to make the ``environment variables`` available. - -.. code-block:: bash - - $ source .ostackrc - -The ``environment variables`` are now available for usage. For testing your -connection run the following command. - -Test your connection -^^^^^^^^^^^^^^^^^^^^ - -If you followed the `installation advices `_ for your specific -operating system, you can use the following command to test the basic -functionality. - -.. code-block:: bash - - $ openstack --os-cloud otc flavor list +Configuration +============= + +You can connect to the Open Telekom Cloud and OpenStack clouds in general +using two approaches. The first one uses a credential file called +``clouds.yaml`` and the other one is to use ``environment variables``. + +Configuring a clouds.yaml file +------------------------------ + +The credential file ``clouds.yaml`` will be queried automatically in different +locations with increasing precedence: + +1. system-wide (/etc/openstack/{clouds,secure}.yaml) +2. Home directory / user space (~/.config/openstack/{clouds,secure}.yaml) +3. Current directory (./{clouds,secure}.yaml) + +A sample clouds.yaml file is listed below to connect with Open Telekom Cloud: + +**clouds.yaml** + +.. code-block:: yaml + + 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: '' + +.. note:: + The name ``otc`` is self-defined and can be changed to any value. + +AK/SK values required for access to some services (i.e. OBS) can +be either configured as shown above in the clouds.yaml/secure.yaml, or +they can be automatically retrieved from the S3_ACCESS_KEY_ID and +S3_SECRET_ACCESS_KEY. + +Test your connection +^^^^^^^^^^^^^^^^^^^^ + +If you followed the `installation advices `_ for your specific +operating system, you can use the following command to test the basic +functionality. + +.. code-block:: bash + + $ openstack --os-cloud otc flavor list + + +Configuration of a Second Project +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Additional connections to other Openstack-clouds or -projects can be added +to the file as shown below: + +**clouds.yaml** + +.. code-block:: yaml + + clouds: + otcfirstproject: + 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: '' + otcsecondproject: + profile: otc + auth: + username: '' + password: '' + project_name: '' + # or project_id: '<123456_PROJECT_ID2>' + user_domain_name: 'OTC00000000001000000xxx' + # or user_domain_id: '<123456_DOMAIN_ID2>' + 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: '' + +Splitting the credentials in clouds.yaml and secure.yaml +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In some scenarios a split of security credentials from the configuration file +is necessary. The optional file ``secure.yaml`` can be used to store the +secret which is left out from ``clouds.yaml``: + +**clouds.yaml** + +.. code-block:: yaml + + clouds: + otc: + profile: otc + auth: + username: '' + 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: '' + +**secure.yaml** + +.. code-block:: yaml + + clouds: + otc: + auth: + password: '' + +Configuration of Environment Variables +-------------------------------------- + +Instead of using the clouds.yaml file, environmnt variables can be configured +to connect to the Open Telekom Cloud. Create a simple file like ``.ostackrc`` +in the home directory and source the file to make the variables available. On +Open Telekom Cloud servers this file exists on bootup and needs to be changed +according to your credentials. + +.. code-block:: bash + + # .ostackrc file + export OS_USERNAME="" + export OS_USER_DOMAIN_NAME= + export OS_PASSWORD= # optional + export OS_TENANT_NAME=eu-de + export OS_PROJECT_NAME= + export OS_AUTH_URL=https://iam.eu-de.otc.t-systems.com:443/v3 + export NOVA_ENDPOINT_TYPE=publicURL + export OS_ENDPOINT_TYPE=publicURL + export CINDER_ENDPOINT_TYPE=publicURL + export OS_VOLUME_API_VERSION=2 + export OS_IDENTITY_API_VERSION=3 + export OS_IMAGE_API_VERSION=2 + +Run the source command to make the ``environment variables`` available. + +.. code-block:: bash + + $ source .ostackrc + +The ``environment variables`` are now available for usage. For testing your +connection run the following command. + +Test your connection +^^^^^^^^^^^^^^^^^^^^ + +If you followed the `installation advices `_ for your specific +operating system, you can use the following command to test the basic +functionality. + +.. code-block:: bash + + $ openstack --os-cloud otc flavor list diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 6b7f1e59b..77642cbe1 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -35,5 +35,6 @@ An application that turns the Python interface of OpenStack SDK and OTC Extensions into a CLI tool. **OTC Extensions:** -An addition to OpenStack SDK with enhanced functionality that is specific for the -Open Telekom Cloud. This is the package you are currently looking at. +An addition to OpenStack SDK with enhanced functionality that is +specific for the Open Telekom Cloud. This is the package you are +currently looking at. diff --git a/doc/source/install/pip_install.rst b/doc/source/install/pip_install.rst index 1645cf23a..d5d63fc13 100644 --- a/doc/source/install/pip_install.rst +++ b/doc/source/install/pip_install.rst @@ -1,175 +1,175 @@ -Installation with PiP Installer -=============================== - -All three packages are written in Python and stored as Python packages in the -PyPi repository. The following section describes the installation of -``OpenStackSDK``, ``otcextensions`` and ``OpenStackClient``. Please remember, -it is not the latest development state. For this purpose the latest sources -needs to be installed. - -PiP Installation in User Space ------------------------------- - -Ubuntu or Debian -^^^^^^^^^^^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, and package manager pip are required: - -.. code-block:: bash - - $ sudo apt update - $ sudo apt install gcc python3 python3-dev python3-pip libssl-dev - -Now, install all libraries and programs at once with the Python package -manager pip. The --user flag provides user wide installation instead of a -global installation. - -.. code-block:: bash - - $ pip3 install otcextensions python-openstackclient --user - - -CentOS -^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, and package manager pip are required. If you want to -use python3 which is recommended, you need to install the epel -repository, first: - -.. code-block:: bash - - $ sudo yum update - $ sudo yum install epel-release - $ sudo yum install gcc python36 python36-devel python36-pip openssl-devel - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - $ pip3 install otcextensions python-openstackclient --user - -Fedora -^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, and package manager pip are required: - - -.. code-block:: bash - - $ sudo dnf upgrade - $ sudo dnf install gcc python3 python3-devel python3-pip openssl-devel - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - $ pip3 install otcextensions python-openstackclient --user - -PiP Installation within a Virtual Environment ---------------------------------------------- - -A virtual environment seperates your installed packages from other -libraries and should be used as well. - -Ubuntu or Debian -^^^^^^^^^^^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, package manager, and virtual environment -are required: - -.. code-block:: bash - - $ sudo apt update - $ sudo apt install gcc python3 python3-dev python3-pip python3-venv libssl-dev - -A virtual environment seperates your installed packages from other libraries -and should be used as well. You can name the virtual environment on your own -desires, in our example it is: "venv". The second command will switch -on "venv": - -.. code-block:: bash - - $ python3 -m venv venv - $ source venv/bin/activate - (venv) $ - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - $ pip install otcextensions openstackclient - - -CentOS -^^^^^^ - -For the installation, following packages are required: a C compiler, Python3 -with developer libraries, package manager, and virtual environment are -required. If you want to use python3 which is recommended, you need to -install the epel repository, first: - - -.. code-block:: bash - - $ sudo yum update - $ sudo yum install epel-release - -No the Python packages are needed: - -.. code-block:: bash - - $ sudo yum update - $ sudo yum install gcc python36 python36-devel python-pip \ - python-virtualenv openssl-devel - -A virtual environment seperates your installed packages from other libraries -and should be used as well. You can name the virtual environment on your own -desires, in our example it is: "venv". The second command will switch -on "venv": - -.. code-block:: bash - - $ python3 -m venv venv - $ source venv/bin/activate - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - $ pip install otcextensions openstackclient - -Fedora (under review) -^^^^^^^^^^^^^^^^^^^^^ - -For the installation, following packages are required: a C compiler, -Python3 with developer libraries, package manager, and a virtual -environment are required: - -.. code-block:: bash - - $ sudo dnf upgrade - $ sudo dnf install gcc python3 python3-devel python3-pip \ - python3-virtualenv openssl-devel - -The virtual environment will be created and activated. You can name the -virtual environment on your own desires, in our example it is "venv": - -.. code-block:: bash - - $ python3 -m venv venv - $ source venv/bin/activate - -Now, install all libraries and programs at once with the Python package -manager pip: - -.. code-block:: bash - - (venv) $ pip install otcextensions openstackclient \ No newline at end of file +Installation with PiP Installer +=============================== + +All three packages are written in Python and stored as Python packages in the +PyPi repository. The following section describes the installation of +``OpenStackSDK``, ``otcextensions`` and ``OpenStackClient``. Please remember, +it is not the latest development state. For this purpose the latest sources +needs to be installed. + +PiP Installation in User Space +------------------------------ + +Ubuntu or Debian +^^^^^^^^^^^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, and package manager pip are required: + +.. code-block:: bash + + $ sudo apt update + $ sudo apt install gcc python3 python3-dev python3-pip libssl-dev + +Now, install all libraries and programs at once with the Python package +manager pip. The --user flag provides user wide installation instead of a +global installation. + +.. code-block:: bash + + $ pip3 install otcextensions python-openstackclient --user + + +CentOS +^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, and package manager pip are required. If you want to +use python3 which is recommended, you need to install the epel +repository, first: + +.. code-block:: bash + + $ sudo yum update + $ sudo yum install epel-release + $ sudo yum install gcc python36 python36-devel python36-pip openssl-devel + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + $ pip3 install otcextensions python-openstackclient --user + +Fedora +^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, and package manager pip are required: + + +.. code-block:: bash + + $ sudo dnf upgrade + $ sudo dnf install gcc python3 python3-devel python3-pip openssl-devel + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + $ pip3 install otcextensions python-openstackclient --user + +PiP Installation within a Virtual Environment +--------------------------------------------- + +A virtual environment seperates your installed packages from other +libraries and should be used as well. + +Ubuntu or Debian +^^^^^^^^^^^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, package manager, and virtual environment +are required: + +.. code-block:: bash + + $ sudo apt update + $ sudo apt install gcc python3 python3-dev python3-pip python3-venv libssl-dev + +A virtual environment seperates your installed packages from other libraries +and should be used as well. You can name the virtual environment on your own +desires, in our example it is: "venv". The second command will switch +on "venv": + +.. code-block:: bash + + $ python3 -m venv venv + $ source venv/bin/activate + (venv) $ + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + $ pip install otcextensions openstackclient + + +CentOS +^^^^^^ + +For the installation, following packages are required: a C compiler, Python3 +with developer libraries, package manager, and virtual environment are +required. If you want to use python3 which is recommended, you need to +install the epel repository, first: + + +.. code-block:: bash + + $ sudo yum update + $ sudo yum install epel-release + +No the Python packages are needed: + +.. code-block:: bash + + $ sudo yum update + $ sudo yum install gcc python36 python36-devel python-pip \ + python-virtualenv openssl-devel + +A virtual environment seperates your installed packages from other libraries +and should be used as well. You can name the virtual environment on your own +desires, in our example it is: "venv". The second command will switch +on "venv": + +.. code-block:: bash + + $ python3 -m venv venv + $ source venv/bin/activate + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + $ pip install otcextensions openstackclient + +Fedora (under review) +^^^^^^^^^^^^^^^^^^^^^ + +For the installation, following packages are required: a C compiler, +Python3 with developer libraries, package manager, and a virtual +environment are required: + +.. code-block:: bash + + $ sudo dnf upgrade + $ sudo dnf install gcc python3 python3-devel python3-pip \ + python3-virtualenv openssl-devel + +The virtual environment will be created and activated. You can name the +virtual environment on your own desires, in our example it is "venv": + +.. code-block:: bash + + $ python3 -m venv venv + $ source venv/bin/activate + +Now, install all libraries and programs at once with the Python package +manager pip: + +.. code-block:: bash + + (venv) $ pip install otcextensions openstackclient diff --git a/doc/source/install/source_install.rst b/doc/source/install/source_install.rst index 7ecaa15af..eaa4fb9df 100644 --- a/doc/source/install/source_install.rst +++ b/doc/source/install/source_install.rst @@ -1,40 +1,41 @@ -Installation from GitHub sources -================================ - -The latest state of the packages can be installed with the following source installation approach. - -Cloning the Github repository: - -.. code-block:: bash - - $ git clone https://github.com/OpenTelekomCloud/python-otcextensions.git - -A virtual environment seperates your installed packages from other libraries -and should be used as well. You can name the virtual environment on your own -desires, in our example it is: "venv". The second command will switch -on "venv": - -.. code-block:: bash - - $ python3 -m venv venv - $ source venv/bin/activate - (venv) $ - -Switch into the new folder which is created by cloning the repository and -install install the project dependencies into the virtual environment: - -.. code-block:: bash - - (venv) $ cd ./python-otcextensions - -Register the CLI plugin using: - -.. code-block:: bash - - (venv) ~/python-otcextensions$ python setup.py install - -Install Openstack-Client binary from pip-Repository: - -.. code-block:: bash - - (venv) ~/python-otcextensions$ pip install openstackclient \ No newline at end of file +Installation from GitHub sources +================================ + +The latest state of the packages can be installed with the following +source installation approach. + +Cloning the Github repository: + +.. code-block:: bash + + $ git clone https://github.com/OpenTelekomCloud/python-otcextensions.git + +A virtual environment seperates your installed packages from other libraries +and should be used as well. You can name the virtual environment on your own +desires, in our example it is: "venv". The second command will switch +on "venv": + +.. code-block:: bash + + $ python3 -m venv venv + $ source venv/bin/activate + (venv) $ + +Switch into the new folder which is created by cloning the repository and +install install the project dependencies into the virtual environment: + +.. code-block:: bash + + (venv) $ cd ./python-otcextensions + +Register the CLI plugin using: + +.. code-block:: bash + + (venv) ~/python-otcextensions$ python setup.py install + +Install Openstack-Client binary from pip-Repository: + +.. code-block:: bash + + (venv) ~/python-otcextensions$ pip install openstackclient diff --git a/doc/source/sdk/architecture.rst b/doc/source/sdk/architecture.rst index a4040e8ad..897f0a22c 100644 --- a/doc/source/sdk/architecture.rst +++ b/doc/source/sdk/architecture.rst @@ -1,18 +1,17 @@ -Architecture Overview and Important Terms -========================================= - -The OTC Extensions contain an abstraction interface layer. Clouds can -do many things, but there are probably only about 10 of them that most -people care about with any regularity. - -If you want to do complicated things, the per-service oriented -portions of the SDK are for you. - -However, if what you want is to be able to write an application that -talks to clouds no matter what crazy choices the deployer has made in -an attempt to be more hipster than their self-entitled narcissist -peers, then the Cloud Abstraction layer is for you. - -Please note that OTC Extensions provides an extension to the -OpenStackSDK. Please refer to it's documentation for the details - \ No newline at end of file +Architecture Overview and Important Terms +========================================= + +The OTC Extensions contain an abstraction interface layer. Clouds can +do many things, but there are probably only about ten of them that +most people care frequently. + +If you want to do complicated things, the per-service oriented +portions of the SDK are for you. However, if what you want is to be +able to write an application that talks to clouds no matter what crazy +choices the deployer has made in an attempt to be more hipster than +their self-entitled narcissist peers, then the Cloud Abstraction layer +is for you. + +The OTC Extensions provide an extension to the OpenStack SDK. Refer to +its documentation for the details: +. diff --git a/doc/source/sdk/getting_started.rst b/doc/source/sdk/getting_started.rst index fc9a46040..149c49921 100644 --- a/doc/source/sdk/getting_started.rst +++ b/doc/source/sdk/getting_started.rst @@ -1,64 +1,63 @@ -Getting Started -=============== - -Connect to the cloud --------------------- - -In order to work with an OpenStack cloud you first need to create a -:class:`~openstack.connection.Connection` using your credentials. A -:class:`~openstack.connection.Connection` can be created in three -ways, using the class itself, config-clouds-yaml (LABEL), or -config-environment-variables (LABEL). It is recommended use -config-clouds-yaml (LABEL) as the same config can be used across tools -and languages. Examples are the OpenStack Client, the Gophercloud -library for golang, and Terraform that is based on that -library. Please be also aware that environment variables carrying -credentials can be a security risk. - -Create Connection -^^^^^^^^^^^^^^^^^ - -To create a :class:`~openstack.connection.Connection` instance, use the -:func:`~openstack.connect` factory function. - -As a next step inject the OTC Extensions into the retrieved connection - -.. code-block:: python - - # An 'otc' is a cloud connection with name 'otc' configured in the clouds.yaml - conn = openstack.connect(cloud='otc') - - # Register OTC Extensions - sdk.register_otc_extensions(conn) - -See a full example at `connect_otc.py `_ - -.. note:: To enable logging, see the ``_ user guide. - -Verify Installation -^^^^^^^^^^^^^^^^^^^ - -You need to have the OpenStack SDK in package `openstacksdk` installed -to work with the OTC Extensions, which are packaged in -`otcextensions`. Thanks to a plugin mechanism, no additional -configuration is needed to use the extension. To verify you are up and -running write a file `demo.py`: - -.. code-block: python - - import openstack as mycloud - - conn = mycloud.connect("otc") - conn.jjjjj.flavors() - -Make sure that you configured your credentials as describe in the -`configuration` section. Run this script with - -.. code-block: bash - $ python demo.py - -It should XXXXXXXX list your XXXXXXXX. - - -with this Python script and run it with -`python demo.py`. \ No newline at end of file +Getting Started +=============== + +Connect to the cloud +-------------------- + +In order to work with an OpenStack cloud you first need to create a +:class:`~openstack.connection.Connection` using your credentials. A +:class:`~openstack.connection.Connection` can be created in three +ways, using the class itself, config-clouds-yaml (LABEL), or +config-environment-variables (LABEL). It is recommended use +config-clouds-yaml (LABEL) as the same config can be used across tools +and languages. Examples are the OpenStack Client, the Gophercloud +library for golang, and Terraform that is based on that +library. Please be also aware that environment variables carrying +credentials can be a security risk. + +Create Connection +^^^^^^^^^^^^^^^^^ + +To create a :class:`~openstack.connection.Connection` instance, use +the :func:`~openstack.connect` factory function. + +As a next step inject the OTC Extensions into the retrieved connection + +.. code-block:: python + + # An 'otc' is a cloud connection with name 'otc' configured in the clouds.yaml + conn = openstack.connect(cloud='otc') + + # Register OTC Extensions + sdk.register_otc_extensions(conn) + +See a full example at `connect_otc.py `_ + +.. note:: To enable logging, see the ``_ user guide. + +Verify Installation +^^^^^^^^^^^^^^^^^^^ + +You need to have the OpenStack SDK in package `openstacksdk` installed +to work with the OTC Extensions, which are packaged in +`otcextensions`. Thanks to a plugin mechanism, no additional +configuration is needed to use the extension. To verify you are up and +running write a file `demo.py`: + +.. code-block: python + + import openstack as mycloud + + conn = mycloud.connect("otc") + conn.jjjjj.flavors() + +Make sure that you configured your credentials as describe in the +`configuration` section. Run this script with + +.. code-block: bash + $ python demo.py + +It should XXXXXXXX list your XXXXXXXX. + +with this Python script and run it with +`python demo.py`. diff --git a/doc/source/sdk/guides/index.rst b/doc/source/sdk/guides/index.rst index 1c64c39d3..f9dedbbb6 100644 --- a/doc/source/sdk/guides/index.rst +++ b/doc/source/sdk/guides/index.rst @@ -1,32 +1,32 @@ -Guides for SDK -============== - -.. toctree:: - :maxdepth: 1 - - deh.rst - logging.rst - -.. _user_guides: - -User Guides ------------ - -SOME TEXT - -OpenStack native User Guides ----------------------------- - -.. toctree:: - :maxdepth: 1 - - Block Storage - Compute - Identity - Image - Key Manager - Message - Microversions - Network - Object Store - Using Cloud Abstration Layer \ No newline at end of file +Guides for SDK +============== + +.. toctree:: + :maxdepth: 1 + + deh + logging + +.. _user_guides: + +User Guides +----------- + +SOME TEXT XXX. + +OpenStack native User Guides +---------------------------- + +.. toctree:: + :maxdepth: 1 + + Block Storage + Compute + Identity + Image + Key Manager + Message + Microversions + Network + Object Store + Using Cloud Abstration Layer diff --git a/doc/source/sdk/index.rst b/doc/source/sdk/index.rst index 05aac3b25..5232713d3 100644 --- a/doc/source/sdk/index.rst +++ b/doc/source/sdk/index.rst @@ -1,26 +1,26 @@ -OpenStack SDK Usage -=================== - -.. toctree:: - :maxdepth: 1 - - architecture - getting_started - guides/index - proxies/index - -The OTC Extensions contain an abstraction interface layer. Clouds can -do many things, but there are probably only about 10 of them that most -people care about with any regularity. - -If you want to do complicated things, the per-service oriented -portions of the SDK are for you. - -However, if what you want is to be able to write an application that -talks to clouds no matter what crazy choices the deployer has made in -an attempt to be more hipster than their self-entitled narcissist -peers, then the Cloud Abstraction layer is for you. - -Please note that OTC Extensions provides an extension to the -OpenStackSDK. Please refer to it's documentation for the details - +Using the OpenStack SDK +======================= + +.. toctree:: + :maxdepth: 1 + + architecture + getting_started + guides/index + proxies/index + +The OTC Extensions contain an abstraction interface layer. Clouds can +do many things, but there are probably only about 10 of them that most +people care about with any regularity. + +If you want to do complicated things, the per-service oriented +portions of the SDK are for you. + +However, if what you want is to be able to write an application that +talks to clouds no matter what crazy choices the deployer has made in +an attempt to be more hipster than their self-entitled narcissist +peers, then the Cloud Abstraction layer is for you. + +OTC Extensions provide an extension to the OpenStackSDK. Refer to its +documentation for the details: +. diff --git a/doc/source/sdk/proxies/auto_scaling.rst b/doc/source/sdk/proxies/auto_scaling.rst index ed26c27af..b8f29f1e1 100644 --- a/doc/source/sdk/proxies/auto_scaling.rst +++ b/doc/source/sdk/proxies/auto_scaling.rst @@ -1,16 +1,17 @@ AutoScaling API =============== -For details on how to use auto scaling, see /sdk/guides/auto_scaling (NEEDS TO BE DONE) +For details on how to use auto scaling, see /sdk/guides/auto_scaling +(NEEDS TO BE DONE). .. automodule:: otcextensions.sdk.auto_scaling.v1._proxy The AutoScaling Class --------------------- -The AS high-level interface is available through the ``auto_scaling`` member of -a :class:`~openstack.connection.Connection` object. The ``auto_scaling`` -member will only be added if the +The AS high-level interface is available through the ``auto_scaling`` +member of a :class:`~openstack.connection.Connection` object. The +``auto_scaling`` member will only be added if the ``otcextensions.sdk.register_otc_extensions(conn)`` method is called. Group Operations diff --git a/doc/source/sdk/proxies/index.rst b/doc/source/sdk/proxies/index.rst index 449a484a7..e3a8de280 100644 --- a/doc/source/sdk/proxies/index.rst +++ b/doc/source/sdk/proxies/index.rst @@ -1,53 +1,53 @@ -Service Proxies -=============== - -.. toctree:: - :maxdepth: 1 - - Anti DDoS Service - AutoScaling Service - Cloud Container Engine v1 - Cloud Container Engine v2 - Cloud Trace Service - Distributed Cache Service - Dedicated Host Service - Distributed Message Service - DNS Service - Key Management Service - Object Block Storage - Volume Backup Service - Relational Database Service RDS V1 - Relational Database Service RDS V3 - -.. _service-proxies: - -Service Proxies ---------------- - -The following service proxies exist on the -:class:`~openstack.connection.Connection`. The service proxies are all always -present on the :class:`~openstack.connection.Connection` object, but the -combination of your ``CloudRegion`` and the catalog of the cloud in question -control which services can be used. - -Links to Native OpenStack Service Proxies ------------------------------------------ - -.. toctree:: - :maxdepth: 1 - - Block Storage - Compute - Database - Identity v2 - Identity v3 - Image v1 - Image v2 - Key Manager - Load Balancer - Message v2 - Network - Object Store - Orchestration - Workflow - +Service Proxies +=============== + +.. toctree:: + :maxdepth: 1 + + Anti DDoS Service + AutoScaling Service + Cloud Container Engine v1 + Cloud Container Engine v2 + Cloud Trace Service + Distributed Cache Service + Dedicated Host Service + Distributed Message Service + DNS Service + Key Management Service + Object Block Storage + Volume Backup Service + Relational Database Service RDS V1 + Relational Database Service RDS V3 + +.. _service-proxies: + +Service Proxies +--------------- + +The following service proxies exist on the +:class:`~openstack.connection.Connection`. The service proxies are all always +present on the :class:`~openstack.connection.Connection` object, but the +combination of your ``CloudRegion`` and the catalog of the cloud in question +control which services can be used. + +Links to Native OpenStack Service Proxies +----------------------------------------- + +.. toctree:: + :maxdepth: 1 + + Block Storage + Compute + Database + Identity v2 + Identity v3 + Image v1 + Image v2 + Key Manager + Load Balancer + Message v2 + Network + Object Store + Orchestration + Workflow + diff --git a/doc/source/sdk/proxies/volume_backup.rst b/doc/source/sdk/proxies/volume_backup.rst index ede7783d6..4540a70a0 100644 --- a/doc/source/sdk/proxies/volume_backup.rst +++ b/doc/source/sdk/proxies/volume_backup.rst @@ -1,16 +1,18 @@ VolumeBackup API ================ -For details on how to use auto scaling, see /sdk/guides/volume_backup (NEEDS TO BE DONE) +For details on how to use auto scaling, see /sdk/guides/volume_backup +(NEEDS TO BE DONE). .. automodule:: otcextensions.sdk.volume_backup.v2._proxy The VolumeBackup Class ---------------------- -The VBS high-level interface is available through the ``volume_backup`` member -of a :class:`~openstack.connection.Connection` object. The ``volume_backup`` -member will only be added if the +The VBS high-level interface is available through the +``volume_backup`` member of a +:class:`~openstack.connection.Connection` object. The +``volume_backup`` member will only be added if the ``otcextensions.sdk.register_otc_extensions(conn)`` method is called. The Backup itself is an OpenStack entity and supported natively as diff --git a/otcextensions/sdk/rds/v3/_proxy.py b/otcextensions/sdk/rds/v3/_proxy.py index ee8eed0c4..358388e06 100644 --- a/otcextensions/sdk/rds/v3/_proxy.py +++ b/otcextensions/sdk/rds/v3/_proxy.py @@ -272,7 +272,7 @@ def find_configuration(self, name_or_id, ignore_missing=True): def create_configuration(self, **attrs): """Create DB Configuration. - :param dict \*\*attrs: Dict to overwrite Configuration object + :param dict **attrs: Dict to overwrite Configuration object :returns: A Configuration Object :rtype: :class:`~otcextensions.sdk.rds.v3.configuration.Configuration` From a76d959e9363f8e5c01828ad7b03e8874fff1aa1 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Thu, 12 Mar 2020 15:14:29 +0000 Subject: [PATCH 16/42] SDK getting started reworked --- doc/source/install/configuration.rst | 4 + doc/source/sdk/getting_started.rst | 112 ++++++++++++++++++--------- otcextensions/sdk/rds/v3/_proxy.py | 2 +- 3 files changed, 80 insertions(+), 38 deletions(-) diff --git a/doc/source/install/configuration.rst b/doc/source/install/configuration.rst index 86a98786a..1123edbf0 100644 --- a/doc/source/install/configuration.rst +++ b/doc/source/install/configuration.rst @@ -5,6 +5,8 @@ You can connect to the Open Telekom Cloud and OpenStack clouds in general using two approaches. The first one uses a credential file called ``clouds.yaml`` and the other one is to use ``environment variables``. +.. _clouds-yaml: + Configuring a clouds.yaml file ------------------------------ @@ -132,6 +134,8 @@ secret which is left out from ``clouds.yaml``: auth: password: '' +.. _environment-variables: + Configuration of Environment Variables -------------------------------------- diff --git a/doc/source/sdk/getting_started.rst b/doc/source/sdk/getting_started.rst index 149c49921..e0ee07b71 100644 --- a/doc/source/sdk/getting_started.rst +++ b/doc/source/sdk/getting_started.rst @@ -1,63 +1,101 @@ Getting Started =============== -Connect to the cloud --------------------- +Verify Installation +------------------- + +``OTC Extensions`` needs to be installed correctly. Please check +:doc:`../install/index` for further instructions. The +``otcextensions`` Python package pulls the ``openstacksdk`` package automatically +as dependency which is needed to create own OpenStack scripts. + +Configure Connection Credentials +-------------------------------- In order to work with an OpenStack cloud you first need to create a :class:`~openstack.connection.Connection` using your credentials. A :class:`~openstack.connection.Connection` can be created in three -ways, using the class itself, config-clouds-yaml (LABEL), or -config-environment-variables (LABEL). It is recommended use -config-clouds-yaml (LABEL) as the same config can be used across tools -and languages. Examples are the OpenStack Client, the Gophercloud -library for golang, and Terraform that is based on that -library. Please be also aware that environment variables carrying -credentials can be a security risk. +ways, using the class itself, :ref:`clouds-yaml`, or +:ref:`environment-variables`. It is recommended use +:ref:`clouds-yaml` as the same config can be used across tools +and languages. Examples are: + +- OpenStack Client +- Gophercloud (library for golang) +- Terraform (based on Gophercloud) -Create Connection -^^^^^^^^^^^^^^^^^ +.. note:: Please be also aware that environment variables carrying + credentials can be a security risk. -To create a :class:`~openstack.connection.Connection` instance, use -the :func:`~openstack.connect` factory function. -As a next step inject the OTC Extensions into the retrieved connection +Creating a Minimal Python Script +-------------------------------- + +At first we need to import `openstack` to get access to all available +:doc:`Proxy ` functions. Enable Logging is an optional +step in the script and can be left out in productive usage. +For communication purposes a :class:`~openstack.connection.Connection` +instance is created to communicate with the Cloud environment. The +`cloud=` represents the :class:`~openstack.connection.Connection` +name defined while creating the ``clouds.yaml`` file in :ref:`clouds-yaml`. +The ``cloud``-variable can be left out if environment variables are +used or only ``one`` Cloud-connection is defined. .. code-block:: python - # An 'otc' is a cloud connection with name 'otc' configured in the clouds.yaml + #!/usr/bin/env python3 + + import openstack + + # optional, enable Logging on + openstack.enable_logging(True) + + # Creates cloud connection + # Parameter cloud='otc' is optional for env variables or single + # clouds.yaml entry. conn = openstack.connect(cloud='otc') - # Register OTC Extensions - sdk.register_otc_extensions(conn) + for server in conn.compute.servers(): + print(server) -See a full example at `connect_otc.py `_ +.. note:: For further examples, see `Examples `_. -.. note:: To enable logging, see the ``_ user guide. +.. note:: For further information about logging, please see + :doc:`Logging User Guide `. -Verify Installation -^^^^^^^^^^^^^^^^^^^ +Run the Script +-------------- + +After saving the script as `list_server.py`. You can simply run it by using +the following command. + +.. code-block:: bash + + python list_server.py -You need to have the OpenStack SDK in package `openstacksdk` installed -to work with the OTC Extensions, which are packaged in -`otcextensions`. Thanks to a plugin mechanism, no additional -configuration is needed to use the extension. To verify you are up and -running write a file `demo.py`: +The output represents all existent OpenStack servers in your Cloud +environment. + +OTC Extensions specific Example for Open Telekom Cloud +------------------------------------------------------ + +The following script uses the OTC Extensions to list all existent CCE Clusters +in your account. + +.. code-block:: python -.. code-block: python + #!/usr/bin/env python3 - import openstack as mycloud + import openstack - conn = mycloud.connect("otc") - conn.jjjjj.flavors() + # openstack.enable_logging(True) + conn = openstack.connect() -Make sure that you configured your credentials as describe in the -`configuration` section. Run this script with + for cce in conn.cce.clusters(): + print(cce) -.. code-block: bash - $ python demo.py +Save the file as `list_cce_clusters.py` and run it with: -It should XXXXXXXX list your XXXXXXXX. +.. code-block:: bash -with this Python script and run it with -`python demo.py`. + python list_cce_clusters.py diff --git a/otcextensions/sdk/rds/v3/_proxy.py b/otcextensions/sdk/rds/v3/_proxy.py index 358388e06..ee8eed0c4 100644 --- a/otcextensions/sdk/rds/v3/_proxy.py +++ b/otcextensions/sdk/rds/v3/_proxy.py @@ -272,7 +272,7 @@ def find_configuration(self, name_or_id, ignore_missing=True): def create_configuration(self, **attrs): """Create DB Configuration. - :param dict **attrs: Dict to overwrite Configuration object + :param dict \*\*attrs: Dict to overwrite Configuration object :returns: A Configuration Object :rtype: :class:`~otcextensions.sdk.rds.v3.configuration.Configuration` From d1a698ad4e6ca71118a6215cbb5aa4e5bfd49966 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 13 Mar 2020 16:32:03 +0000 Subject: [PATCH 17/42] fix RDS proxy attrs --- otcextensions/sdk/rds/v3/_proxy.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/otcextensions/sdk/rds/v3/_proxy.py b/otcextensions/sdk/rds/v3/_proxy.py index ee8eed0c4..985a2cb2e 100644 --- a/otcextensions/sdk/rds/v3/_proxy.py +++ b/otcextensions/sdk/rds/v3/_proxy.py @@ -272,7 +272,7 @@ def find_configuration(self, name_or_id, ignore_missing=True): def create_configuration(self, **attrs): """Create DB Configuration. - :param dict \*\*attrs: Dict to overwrite Configuration object + :param dict attrs: Dict to overwrite Configuration object :returns: A Configuration Object :rtype: :class:`~otcextensions.sdk.rds.v3.configuration.Configuration` From 09e7375ea23c4a783971d4c12ee0ab041947ec73 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 13 Mar 2020 17:36:02 +0000 Subject: [PATCH 18/42] smaller fixes --- doc/source/index.rst | 5 +++-- doc/source/install/configuration.rst | 6 +++++- doc/source/sdk/getting_started.rst | 8 ++++---- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 0cb6f034b..236a94c0a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -37,8 +37,9 @@ Installation and Configuration The :doc:`installation ` guide explains system administrators and developers how to setup the project from operation system packages, from pip, directly from sources and other -installation forms. OTC Extensions are very easy to configure: All -credentials can be configured in one or two files. +installation forms. OTC Extensions are very easy to +:doc:`configure `. All credentials can be configured +in one or two files. Working with the CLI tool diff --git a/doc/source/install/configuration.rst b/doc/source/install/configuration.rst index 1123edbf0..a6a167a27 100644 --- a/doc/source/install/configuration.rst +++ b/doc/source/install/configuration.rst @@ -179,4 +179,8 @@ functionality. .. code-block:: bash - $ openstack --os-cloud otc flavor list + $ openstack flavor list + +.. note:: + You don't need to specify the `--os-cloud` parameter when environment + variables are used. diff --git a/doc/source/sdk/getting_started.rst b/doc/source/sdk/getting_started.rst index e0ee07b71..1588cec8e 100644 --- a/doc/source/sdk/getting_started.rst +++ b/doc/source/sdk/getting_started.rst @@ -6,8 +6,8 @@ Verify Installation ``OTC Extensions`` needs to be installed correctly. Please check :doc:`../install/index` for further instructions. The -``otcextensions`` Python package pulls the ``openstacksdk`` package automatically -as dependency which is needed to create own OpenStack scripts. +``otcextensions`` Python package pulls the ``openstacksdk`` package +automatically as dependency which is needed to create own OpenStack scripts. Configure Connection Credentials -------------------------------- @@ -91,8 +91,8 @@ in your account. # openstack.enable_logging(True) conn = openstack.connect() - for cce in conn.cce.clusters(): - print(cce) + for cluster in conn.cce.clusters(): + print(cluster) Save the file as `list_cce_clusters.py` and run it with: From a66350cf75876a391d94eae62ba8db8244c68e7b Mon Sep 17 00:00:00 2001 From: Nils Magnus Date: Wed, 18 Mar 2020 11:06:46 +0100 Subject: [PATCH 19/42] streamline the main page documentation --- doc/source/index.rst | 50 +++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 236a94c0a..10b4cfccf 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,20 +1,22 @@ Welcome to the OTC Extensions of the OpenStack SDK and CLI! =========================================================== -Accessing the `OpenStack API`_ directly can be tedious. The `OpenStack -SDK`_ is a Python based client library that simplifies building -applications to work with OpenStack clouds. **This project, OTC -Extensions,** augments this SDK and adds extra functionality offered -by the `Open Telekom Cloud`_. The OTC Extensions serve two purposes: -Firstly, they provide Python classes and methods to attach your own -code to the cloud. For example, `Ansible modules`_ use this -way. Secondly, the OTC Extensions automatically extend the `OpenStack -Client`_, the CLI tool to manage the OpenStack cloud. +There are several ways to access an OpenStack cloud. The ultimate way +is accessing the `OpenStack API`_ directly. But that can be very +tedious. The `OpenStack SDK`_ is a Python based client library that +simplifies building applications to work with OpenStack clouds. The +`OpenStack Client`_ is its equivalent on the command line. + +**This project, OTC Extensions,** adds extra functionality to the SDK +and the CLI offered by the `Open Telekom Cloud`_. Technically, the OTC +Extensions provide Python classes and methods to attach your own code +to the cloud. They also integrate seamless into the OpenStack Client, +providing many extra commands. Content ------- -This documentation is split into four sections, adressing major use +This documentation is split into sections, adressing major use cases. Additionally some auxiliary documentation is available: .. toctree:: @@ -37,9 +39,9 @@ Installation and Configuration The :doc:`installation ` guide explains system administrators and developers how to setup the project from operation system packages, from pip, directly from sources and other -installation forms. OTC Extensions are very easy to -:doc:`configure `. All credentials can be configured -in one or two files. +installation forms. OTC Extensions are very easy to :doc:`configure +`. All credentials can be configured in one or +two files. Working with the CLI tool @@ -47,16 +49,16 @@ Working with the CLI tool Users who want to access Open Telekom Cloud specific services with :doc:`command line tools ` for a shell like Bash find -documentation of all of their operations and properties in this section. +documentation of all of their operations and properties in this +section. Writing your own Scripts for the Cloud -------------------------------------- Developers, who plan to write own Python code, may access the API more -easily by using the OTC Extensions' classes and methods. The -:doc:`SDK interfaces ` are documented in this -section. +easily by using the OTC Extensions' classes and methods. The :doc:`SDK +interfaces ` are documented in this section. Contribute to the Project @@ -76,20 +78,20 @@ available: * In a :doc:`glossary ` important terms and their naming conventions are described. -* There is a :doc:`history ` explaing the ancestry - of this project. This may or may not be insightful if you want to +* The :doc:`history ` explains the ancestry of + this project. This may or may not be insightful if you want to understand the projects architecture. -* There is a :doc:`release history ` - available. +* The project keeps a :doc:`release history + `. * A list of :doc:`issues ` is maintained. * Currently 13 services are :doc:`covered ` by the OTC extensions. -.. _OpenStack SDK: https://docs.openstack.org/openstacksdk/ .. _OpenStack API: https://docs.openstack.org/api-quick-start/ -.. _Open Telekom Cloud: https://open-telekom-cloud.com/ -.. _Ansible modules: https://github.com/OpenTelekomCloud/ansible-collections/ +.. _OpenStack SDK: https://docs.openstack.org/openstacksdk/ .. _OpenStack Client: https://docs.openstack.org/python-openstackclient/ +.. _Ansible modules: https://github.com/OpenTelekomCloud/ansible-collections/ +.. _Open Telekom Cloud: https://open-telekom-cloud.com/ From 7ced6850df6d5013493b9a973a2f618b85dec5c7 Mon Sep 17 00:00:00 2001 From: Nils Magnus Date: Wed, 18 Mar 2020 11:42:46 +0100 Subject: [PATCH 20/42] fix spelling and language --- doc/source/index.rst | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 10b4cfccf..08b18c3d7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -36,12 +36,11 @@ cases. Additionally some auxiliary documentation is available: Installation and Configuration ------------------------------ -The :doc:`installation ` guide explains system -administrators and developers how to setup the project from operation -system packages, from pip, directly from sources and other -installation forms. OTC Extensions are very easy to :doc:`configure -`. All credentials can be configured in one or -two files. +The :doc:`installation guide ` explains to system +administrators and developers how to setup the project from system +packages, from pip, and directly from sources. OTC Extensions are easy +to :doc:`configure `. All credentials can be +configured conveniently in a few files. Working with the CLI tool @@ -56,31 +55,31 @@ section. Writing your own Scripts for the Cloud -------------------------------------- -Developers, who plan to write own Python code, may access the API more -easily by using the OTC Extensions' classes and methods. The :doc:`SDK -interfaces ` are documented in this section. +Developers writing own Python code may access the API easily by using +the OTC Extensions' classes and methods. The :doc:`SDK interfaces +` are documented in this section. Contribute to the Project ------------------------- -Developers, who want to :doc:`contribute ` to the -project, find helpful background information and architecture -specification of OTC Extensions here. +To :doc:`contribute ` to the project itself, +developers find helpful background information and architecture +specification of OTC Extensions it this section. General Information ------------------- -Adding to that, there is some general background information +There is general background information about the OTC Extensions available: -* In a :doc:`glossary ` important terms and their - naming conventions are described. +* A :doc:`glossary ` describes important terms + and their naming conventions. * The :doc:`history ` explains the ancestry of this project. This may or may not be insightful if you want to - understand the projects architecture. + understand the project's architecture. * The project keeps a :doc:`release history `. From f7e598a3cbd5c1268cfd30d8f465915a8ff20b5e Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Wed, 18 Mar 2020 11:14:18 +0000 Subject: [PATCH 21/42] auto-scaling started --- doc/source/sdk/guides/auto_scaling.rst | 48 ++++++++++++++++++++++++++ doc/source/sdk/guides/index.rst | 4 +++ examples/auto_scaling/create_config.py | 36 +++++++++++++++++++ examples/auto_scaling/find_config.py | 24 +++++++++++++ examples/auto_scaling/init.py | 0 examples/auto_scaling/list_configs.py | 19 ++++++++++ 6 files changed, 131 insertions(+) create mode 100644 doc/source/sdk/guides/auto_scaling.rst create mode 100644 examples/auto_scaling/create_config.py create mode 100644 examples/auto_scaling/find_config.py create mode 100644 examples/auto_scaling/init.py create mode 100644 examples/auto_scaling/list_configs.py diff --git a/doc/source/sdk/guides/auto_scaling.rst b/doc/source/sdk/guides/auto_scaling.rst new file mode 100644 index 000000000..d94fc507d --- /dev/null +++ b/doc/source/sdk/guides/auto_scaling.rst @@ -0,0 +1,48 @@ +Auto-Scaling (AS) +================= + +.. contents:: Table of Contents + :local: + +Auto-Scaling Configuration +-------------------------- + +An Auto-Scaling (AS) configuration is a template of Elastic Cloud Servers in +an AS group. It defines the specifications of the instances to be added to +the AS group. The AS configuration is decoupled from the AS group and can +be used several times in different groups. Up to 100 AS configurations can +be created for each user. + +List Auto-Scaling configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to query all Auto-Scaling configurations and to filter +the output with query parameters. + +.. literalinclude:: ../examples/auto_scaling/list_configs.py + :lines: 13-19 + +Create Auto-Scaling configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to create an Auto-Scaling Configuration instance with parameters. + +.. literalinclude:: ../examples/auto_scaling/create_config.py + :lines: 16-36 + +Find Auto-Scaling configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to find an Auto-Scaling Configuration instance by name or id. + +.. literalinclude:: ../examples/auto_scaling/find_config.py + :lines: 16-24 + +Auto-Scaling Group +------------------ + +An Auto-Scaling (AS) group consists of a collection of instances that apply +to the same scaling scenario. An AS group specifies parameters, such as the +maximum number of instances, expected number of instances, minimum number +of instances, VPC, subnet, and load balancing. Each user can create a maximum +of 25 AS groups by default. diff --git a/doc/source/sdk/guides/index.rst b/doc/source/sdk/guides/index.rst index f9dedbbb6..18433aa49 100644 --- a/doc/source/sdk/guides/index.rst +++ b/doc/source/sdk/guides/index.rst @@ -1,9 +1,13 @@ Guides for SDK ============== +Open Telekom Cloud related User Guides +-------------------------------------- + .. toctree:: :maxdepth: 1 + auto_scaling deh logging diff --git a/examples/auto_scaling/create_config.py b/examples/auto_scaling/create_config.py new file mode 100644 index 000000000..c527ec88a --- /dev/null +++ b/examples/auto_scaling/create_config.py @@ -0,0 +1,36 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Create Auto-Scaling Configuration. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +attrs = { + 'name': 'test-config', + 'instance_config': { + 'flavorRef': 's2.medium.1', + 'imageRef': '1616e0b6-503a-4698-946f-cf9942c4c73b', + 'disk': [{ + 'size': 20, + 'volume_type': 'SATA', + 'disk_type': 'SYS' + }], + 'key_name': 'test-key', + } +} + +config = conn.auto_scaling.create_config(**attrs) +print(config) diff --git a/examples/auto_scaling/find_config.py b/examples/auto_scaling/find_config.py new file mode 100644 index 000000000..177fc6e4f --- /dev/null +++ b/examples/auto_scaling/find_config.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Find Auto-Scaling Configuration. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +config = "config_name_or_id" + +config = conn.auto_scaling.find_config(config) +print(config) diff --git a/examples/auto_scaling/init.py b/examples/auto_scaling/init.py new file mode 100644 index 000000000..e69de29bb diff --git a/examples/auto_scaling/list_configs.py b/examples/auto_scaling/list_configs.py new file mode 100644 index 000000000..08b96fa4b --- /dev/null +++ b/examples/auto_scaling/list_configs.py @@ -0,0 +1,19 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +for config in conn.auto_scaling.configs(): + print(config) From e5e8d22cfcda029dde189002a62fd17f1b89319c Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Thu, 19 Mar 2020 15:00:55 +0000 Subject: [PATCH 22/42] AS Config finished --- doc/source/sdk/guides/auto_scaling.rst | 58 +++++++++++++++++--- examples/auto_scaling/batch_delete_config.py | 26 +++++++++ examples/auto_scaling/create_config.py | 4 +- examples/auto_scaling/create_group.py | 37 +++++++++++++ examples/auto_scaling/delete_config.py | 23 ++++++++ examples/auto_scaling/get_config.py | 24 ++++++++ examples/auto_scaling/list_configs.py | 3 + examples/auto_scaling/list_groups.py | 22 ++++++++ 8 files changed, 186 insertions(+), 11 deletions(-) create mode 100644 examples/auto_scaling/batch_delete_config.py create mode 100644 examples/auto_scaling/create_group.py create mode 100644 examples/auto_scaling/delete_config.py create mode 100644 examples/auto_scaling/get_config.py create mode 100644 examples/auto_scaling/list_groups.py diff --git a/doc/source/sdk/guides/auto_scaling.rst b/doc/source/sdk/guides/auto_scaling.rst index d94fc507d..a9ca7a412 100644 --- a/doc/source/sdk/guides/auto_scaling.rst +++ b/doc/source/sdk/guides/auto_scaling.rst @@ -13,31 +13,62 @@ the AS group. The AS configuration is decoupled from the AS group and can be used several times in different groups. Up to 100 AS configurations can be created for each user. -List Auto-Scaling configurations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +List Auto-Scaling Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This interface is used to query all Auto-Scaling configurations and to filter the output with query parameters. .. literalinclude:: ../examples/auto_scaling/list_configs.py - :lines: 13-19 + :lines: 16-22 -Create Auto-Scaling configurations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Create Auto-Scaling Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This interface is used to create an Auto-Scaling Configuration instance with parameters. +This interface is used to create an Auto-Scaling Configuration instance with +parameters. .. literalinclude:: ../examples/auto_scaling/create_config.py :lines: 16-36 -Find Auto-Scaling configurations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Get Auto-Scaling Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to get an Auto-Scaling Configuration by ID +or an instance of :class:`~otcextensions.sdk.auto_scaling.v1.config.Config`. + +.. literalinclude:: ../examples/auto_scaling/get_config.py + :lines: 16-24 -This interface is used to find an Auto-Scaling Configuration instance by name or id. +Find Auto-Scaling Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to find an Auto-Scaling Configuration instance by +name or id. .. literalinclude:: ../examples/auto_scaling/find_config.py :lines: 16-24 +Delete Auto-Scaling Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to delete an Auto-Scaling Configuration instance by id +or an instance of :class:`~otcextensions.sdk.auto_scaling.v1.config.Config`. + +.. literalinclude:: ../examples/auto_scaling/delete_config.py + :lines: 16-23 + +Batch Delete Auto-Scaling Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to delete multiple Auto-Scaling Configuration instances +by id or an instance of +:class:`~otcextensions.sdk.auto_scaling.v1.config.Config`. + +.. literalinclude:: ../examples/auto_scaling/batch_delete_config.py + :lines: 16-26 + + Auto-Scaling Group ------------------ @@ -46,3 +77,12 @@ to the same scaling scenario. An AS group specifies parameters, such as the maximum number of instances, expected number of instances, minimum number of instances, VPC, subnet, and load balancing. Each user can create a maximum of 25 AS groups by default. + +List Auto-Scaling Groups +^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to query all Auto-Scaling Groups and to filter +the output with query parameters. + +.. literalinclude:: ../examples/auto_scaling/list_groups.py + :lines: 16-22 diff --git a/examples/auto_scaling/batch_delete_config.py b/examples/auto_scaling/batch_delete_config.py new file mode 100644 index 000000000..7e4b72ec1 --- /dev/null +++ b/examples/auto_scaling/batch_delete_config.py @@ -0,0 +1,26 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Delete multiple Auto-Scaling Configurations by id or instance of class Config +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +config1 = conn.auto_scaling.find_config('test-config1') +config2 = conn.auto_scaling.find_config('test-config2') + +configs = [config1, config2] + +conn.auto_scaling.batch_delete_configs(configs) diff --git a/examples/auto_scaling/create_config.py b/examples/auto_scaling/create_config.py index c527ec88a..71249cbaa 100644 --- a/examples/auto_scaling/create_config.py +++ b/examples/auto_scaling/create_config.py @@ -20,14 +20,14 @@ attrs = { 'name': 'test-config', - 'instance_config': { + 'instance_config': { 'flavorRef': 's2.medium.1', 'imageRef': '1616e0b6-503a-4698-946f-cf9942c4c73b', 'disk': [{ 'size': 20, 'volume_type': 'SATA', 'disk_type': 'SYS' - }], + }], 'key_name': 'test-key', } } diff --git a/examples/auto_scaling/create_group.py b/examples/auto_scaling/create_group.py new file mode 100644 index 000000000..ee488a489 --- /dev/null +++ b/examples/auto_scaling/create_group.py @@ -0,0 +1,37 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Create Auto-Scaling Group. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +attrs = { + "scaling_group_name": "TestGroup", + "scaling_configuration_id": "0d138717-e79d-4fa7-b8aa-37ddec1b3ce7", + "desire_instance_number": 0, + "min_instance_number": 0, + "max_instance_number": 10, + "vpc_id": "26ca2783-dc40-4e3a-95b1-5a0756441e12", + "available_zones": ["eu-de-01", "eu-de-03"], + "networks": [ + { + "id": "25d24fc8-d019-4a34-9fff-0a09fde6a9cb" + } + ] +} + +group = conn.auto_scaling.create_group(**attrs) +print(group) diff --git a/examples/auto_scaling/delete_config.py b/examples/auto_scaling/delete_config.py new file mode 100644 index 000000000..1dff5e3f5 --- /dev/null +++ b/examples/auto_scaling/delete_config.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Delete Auto-Scaling Configuration by id or instance of class Config +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +config_id = '1234567-ad7a-48ce-8f92-b55c651439d2' +conn.auto_scaling.delete_config(config_id) diff --git a/examples/auto_scaling/get_config.py b/examples/auto_scaling/get_config.py new file mode 100644 index 000000000..194f394a5 --- /dev/null +++ b/examples/auto_scaling/get_config.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get Auto-Scaling Configuration by id or object +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +config_id = "1234567-6aa0-4c8b-b350-3bd937addeb7" +config = conn.auto_scaling.get_config(config_id) +print(config) diff --git a/examples/auto_scaling/list_configs.py b/examples/auto_scaling/list_configs.py index 08b96fa4b..3fc9a49a8 100644 --- a/examples/auto_scaling/list_configs.py +++ b/examples/auto_scaling/list_configs.py @@ -10,6 +10,9 @@ # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations # under the License. +""" +List all Auto-Scaling Configurations +""" import openstack openstack.enable_logging(True) diff --git a/examples/auto_scaling/list_groups.py b/examples/auto_scaling/list_groups.py new file mode 100644 index 000000000..4bcc31811 --- /dev/null +++ b/examples/auto_scaling/list_groups.py @@ -0,0 +1,22 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List all Auto-Scaling Groups +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +for group in conn.auto_scaling.groups(): + print(group) From 5337a70529f9c1b81d4ec5d6ea964c0f1d27e233 Mon Sep 17 00:00:00 2001 From: Nils Magnus Date: Thu, 19 Mar 2020 16:08:28 +0100 Subject: [PATCH 23/42] explain details about installation options --- doc/source/install/index.rst | 103 +++++++++++++++++++++++++---------- 1 file changed, 75 insertions(+), 28 deletions(-) diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 77642cbe1..50eac4e40 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -1,40 +1,87 @@ Installation ============ +There are several install options for OTC Extensions to enhance the +native `OpenStack Client`_ and to extend the `OpenStack SDK`_. Once +installed, they cover additional `Open Telekom Cloud`_ services and +provide extra functionality on top of the stock OpenStack SDK and CLI. + .. toctree:: :maxdepth: 3 - pip_install.rst - source_install.rst - -There are several ways to install OTC Extensions to enhance the native -OpenStack Client and to extend the OpenStack SDK to cover the -additional Open Telekom Cloud services providing a larger -functionality on top of OpenStack. - -The easiest way is to use the Python pip installer which is working -distribution independent and can be used in an isolated virtual environment -as described below. Ansible can be used to install python-otcextensions on -various operating systems, too by using the following Ansible Role: -https://github.com/OpenTelekomCloud/ansible-role-otcextensions . -There are also ready-made installation packages for various operating -systems which have their own versions, package names and sometimes bugs. -A repository based on openSUSE's build services tries to cover these issues -which is available under: -https://build.opensuse.org/project/show/Cloud:OTC:Tools:OpenStack. + pip_install + source_install Overview of Related Packages ---------------------------- -**OpenStack SDK:** -A library on the client side that translates Python function calls into -API calls to an OpenStack cloud. +The OTC Extensions are, as most software in OpenStack, written in +Python and are eventually a Python package. These packages come with +dependencies to other packages. Usually a package manager such as pip +is used to resolve those dependencies or all requirements are bundled +in a single packet. These are the main packages and their relations to +each other: + +**OpenStack SDK:** A library on the client side that translates Python +function calls into API calls to an OpenStack cloud. It depends only +on other, internal Python packages. + +**OpenStack Client:** An application that turns the Python interface +of OpenStack SDK and OTC Extensions into a CLI tool. If installed, it +requires the SDK. + +**OTC Extensions:** An addition to OpenStack SDK with enhanced +functionality that is specific for the Open Telekom Cloud. This is the +package you are currently looking at. It requires the SDK since it +extends its interfaces. If it is installed as a Python package it is +detected and integrated automatically by the other two packages +without further installation or configuration. + +So effectively, using a package manager like pip it is sufficient to +install the packages like this: + +.. code-block: console + $ pip install openstackclcient otcextensions -**OpenStack Client:** -An application that turns the Python interface of OpenStack SDK and -OTC Extensions into a CLI tool. +Other packaging methods may or may not have these dependencies built +in already. + + +Installation Options +-------------------- + +There are a number of alternatives available to install OTC Extensions +(including the SDK and CLI): + +* **Installing from operating system packages (deb, rpm, yum, dnf):** + This is a very easy way that is also easy to revert. The downside of + this aproach is that operating system packages for the major + distributions are often quite outdated, as many of the internal + dependencies are also often outdated. You often experience a backlog + of several months up to years behind the latest development. + +* **Installing with a Python package manager (pip):** Python comes + with its own package manager `pip` for the `Python Package Index + (PyPI)`_. That is today the standard way to install Python + packages. All other described options use this method under the + hood. This way is operating system independent. Installing with + `pip` comes with three sub-options: Installing system-wide, for a + single user, or inside a virtual environemt. **This is the + recommended way to install OTC Extensions.** + +* **Installing from sources:** All related projects are hosted on + public source code repositories. So if you need a bleeding edge + feature or want to contribute directly to the project yourself, + installation from sources is for you. It requires some extra steps, + though. + +There are also ready-made installation packages for various operating +systems which have their own versions, package names and sometimes +bugs. A repository based on openSUSE's build services tries to cover +these issues which is available under: +https://build.opensuse.org/project/show/Cloud:OTC:Tools:OpenStack. -**OTC Extensions:** -An addition to OpenStack SDK with enhanced functionality that is -specific for the Open Telekom Cloud. This is the package you are -currently looking at. +.. _OpenStack SDK: https://docs.openstack.org/openstacksdk/ +.. _OpenStack Client: https://docs.openstack.org/python-openstackclient/ +.. _Open Telekom Cloud: https://open-telekom-cloud.com/ +.. _Python Package Index (PyPI): https://pypi.org/ From 577e2f2df368a92b7f7cf3fe70f0cd18892bcbdc Mon Sep 17 00:00:00 2001 From: Nils Magnus Date: Thu, 19 Mar 2020 16:22:36 +0100 Subject: [PATCH 24/42] list authors --- AUTHORS | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 AUTHORS diff --git a/AUTHORS b/AUTHORS new file mode 100644 index 000000000..139c134f8 --- /dev/null +++ b/AUTHORS @@ -0,0 +1,7 @@ +Artem Goncharov +György Hodi +Kristian Kucerak +Nils Magnus +Tino Schreiber +Vineet Pruthi <48789821+vineet-pruthi@users.noreply.github.com> +Zsolt Nagy From 9f04b7155c6de821aabb40436a0d7408af5edff6 Mon Sep 17 00:00:00 2001 From: Nils Magnus Date: Fri, 20 Mar 2020 01:22:48 +0100 Subject: [PATCH 25/42] clean up the top directory docs --- .gitignore | 1 - CONTRIBUTING.rst | 49 ++++----- HACKING.rst | 108 -------------------- README-save | 137 +++++++++++++++++++++++++ README.rst | 160 +++++++++++++++--------------- doc/source/contributor/coding.rst | 155 ++++++++++++++++++----------- doc/source/contributor/index.rst | 46 +++++---- 7 files changed, 353 insertions(+), 303 deletions(-) delete mode 100644 HACKING.rst create mode 100644 README-save diff --git a/.gitignore b/.gitignore index 919ef00d7..cad5c2103 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,6 @@ .stestr/ .testrepository .tox -AUTHORS build ChangeLog dist diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 57b6bf563..84fe3a5dd 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,45 +1,30 @@ -.. _contributing: +Contributing to OTC Extensions +============================== -=================================== -Contributing to python-openstacksdk -=================================== +OTC Extension are developed as a community effort initiated by +T-Systems International GmbH for the Open Telekom Cloud under an Open +Source license. All code is licensed under the Apache 2.0 license. -If you're interested in contributing to the python-openstacksdk project, -the following will help get you started. +We are happily accepting pull requests. Please reach out to the +project to sort out legal code contribution. If you're interested in +contributing to the project, have a look in the `contributors +section`_ of our documentation. -Contributor License Agreement ------------------------------ +We follow the recommendation of the `OpenStack's workflow`_ for open +source contributions and value the four opens. -.. index:: - single: license; agreement - -In order to contribute to the python-openstacksdk project, you need to have -signed OpenStack's contributor's agreement. - -Please read `DeveloperWorkflow`_ before sending your first patch for review. -Pull requests submitted through GitHub will be ignored. - -.. seealso:: - - * http://wiki.openstack.org/HowToContribute - * http://wiki.openstack.org/CLA - -.. _DeveloperWorkflow: http://docs.openstack.org/infra/manual/developers.html#development-workflow Project Hosting Details -------------------------- +----------------------- Project Documentation - http://docs.openstack.org/sdks/python/openstacksdk/ + https://python-otcextensions.readthedocs.io/ Bug tracker - https://bugs.launchpad.net/python-openstacksdk - -Mailing list (prefix subjects with ``[sdk]`` for faster responses) - http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev + https://github.com/opentelekomcloud/python-otcextensions/issues Code Hosting - https://git.openstack.org/cgit/openstack/python-openstacksdk + https://github.com/opentelekomcloud/python-otcextensions/ -Code Review - https://review.openstack.org/#/q/status:open+project:openstack/python-openstacksdk,n,z +.. _contributors section: https://python-otcextensions.readthedocs.io/en/latest/contributor/ +.. _OpenStack's workflow: http://docs.openstack.org/infra/manual/developers.html#development-workflow diff --git a/HACKING.rst b/HACKING.rst deleted file mode 100644 index 61803e9a4..000000000 --- a/HACKING.rst +++ /dev/null @@ -1,108 +0,0 @@ -OpenStack Style Commandments -============================ - -- Step 1: Read the OpenStack Style Commandments - https://docs.openstack.org/hacking/latest/ -- Step 2: Read on - -General -------- -- thou shalt not violate causality in our time cone, or else - -Docstrings ----------- - -Docstrings should ONLY use triple-double-quotes (``"""``) - -Single-line docstrings should NEVER have extraneous whitespace -between enclosing triple-double-quotes. - -Deviation! Sentence fragments do not have punctuation. Specifically in the -command classes the one line docstring is also the help string for that -command and those do not have periods. - - """A one line docstring looks like this""" - -Calling Methods ---------------- - -Deviation! When breaking up method calls due to the 79 char line length limit, -use the alternate 4 space indent. With the first argument on the succeeding -line all arguments will then be vertically aligned. Use the same convention -used with other data structure literals and terminate the method call with -the last argument line ending with a comma and the closing paren on its own -line indented to the starting line level. - - unnecessarily_long_function_name( - 'string one', - 'string two', - kwarg1=constants.ACTIVE, - kwarg2=['a', 'b', 'c'], - ) - -Text encoding -------------- - -Note: this section clearly has not been implemented in this project yet, it is -the intention to do so. - -All text within python code should be of type 'unicode'. - - WRONG: - - >>> s = 'foo' - >>> s - 'foo' - >>> type(s) - - - RIGHT: - - >>> u = u'foo' - >>> u - u'foo' - >>> type(u) - - -Transitions between internal unicode and external strings should always -be immediately and explicitly encoded or decoded. - -All external text that is not explicitly encoded (database storage, -commandline arguments, etc.) should be presumed to be encoded as utf-8. - - WRONG: - - infile = open('testfile', 'r') - mystring = infile.readline() - myreturnstring = do_some_magic_with(mystring) - outfile.write(myreturnstring) - - RIGHT: - - infile = open('testfile', 'r') - mystring = infile.readline() - mytext = mystring.decode('utf-8') - returntext = do_some_magic_with(mytext) - returnstring = returntext.encode('utf-8') - outfile.write(returnstring) - -Python 3.x Compatibility ------------------------- - -OpenStackClient strives to be Python 3.3 compatible. Common guidelines: - -* Convert print statements to functions: print statements should be converted - to an appropriate log or other output mechanism. -* Use six where applicable: x.iteritems is converted to six.iteritems(x) - for example. - -Running Tests -------------- - -Note: Oh boy, are we behind on writing tests. But they are coming! - -The testing system is based on a combination of tox and testr. If you just -want to run the whole suite, run `tox` and all will be fine. However, if -you'd like to dig in a bit more, you might want to learn some things about -testr itself. A basic walkthrough for OpenStack can be found at -http://wiki.openstack.org/testr diff --git a/README-save b/README-save new file mode 100644 index 000000000..6ba91b7f5 --- /dev/null +++ b/README-save @@ -0,0 +1,137 @@ +OTC Extensions +============== + +.. image:: https://travis-ci.org/OpenTelekomCloud/python-otcextensions.svg?branch=master + :target: https://travis-ci.org/OpenTelekomCloud/python-otcextensions + +.. image:: https://readthedocs.org/projects/python-otcextensions/badge/?version=latest + :target: http://python-otcextensions.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + +OTCExtensions is a project to bring OTC extensions into the native OpenStack +toolstack. Covered are currently following items: + +* `python-openstacksdk` +* `python-openstackclient` + +The primary goal is to provide a possibility to use native OpenStack SDK and +CLI with the OTC additional services + +Getting Started +=============== + +The very first step to get started is to install otcextensions into your +system. For this please follow installation instructions_ + +.. _instructions: http://python-otcextensions.readthedocs.io/en/latest/install/index.html + +Next step would be logically configuration + +Configuration +============= + +openstack.config +================ + +The recommended way, since it is the most efficient way to configure both SDK +and the CLI in one place + +``openstack.config`` will find cloud configuration for as few as 1 clouds and +as many as you want to put in a config file. It will read environment variables +and config files, and it also contains some vendor specific default values so +that you don't have to know extra info to use OpenStack + +* If you have a config file, you will get the clouds listed in it +* If you have environment variables, you will get a cloud named `envvars` +* If you have neither, you will get a cloud named `defaults` with base defaults + +Sometimes an example is nice. + +Create a ``clouds.yaml`` file: + +.. code-block:: yaml + + clouds: + otc: + auth: + username: 'USER_NAME' + password: 'PASS' + 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 # !Important + ak: 'AK_VALUE' # AK/SK pair for access to OBS + sk: 'SK_VALUE' + +Please note: ``openstack.config`` will look for a file called ``clouds.yaml`` +in the following locations: + +* Current Directory +* ``~/.config/openstack`` +* ``/etc/openstack`` + +AK/SK values required for access to some services (i.e. OBS) can be either +configured as shown above in the clouds.yaml/secure.yaml, or they can be +automatically retrieved from the S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY. +Values from the clouds.yaml/secure.yaml take precedence over the ones from +environment. + +With this configuration you can start using openstackCLI simply ``openstack +--os-cloud otc`` + +More information at https://developer.openstack.org/sdks/python/openstacksdk/users/config + +Old style way +============= + +The CLI can be configured via environment variables and command-line options as +listed in +https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html +or https://developer.openstack.org/sdks/python/openstacksdk/users/config. + +Authentication using username/password is often used:: + + export OS_AUTH_URL= + export OS_IDENTITY_API_VERSION=3 + export OS_PROJECT_NAME= + export OS_PROJECT_DOMAIN_NAME= + export OS_USERNAME= + export OS_USER_DOMAIN_NAME= + export OS_PASSWORD= # (optional) + export S3_ACCESS_KEY_ID= + export S3_SECRET_ACCESS_KEY= + +The corresponding command-line options look very similar:: + + --os-auth-url + --os-identity-api-version 3 + --os-project-name + --os-project-domain-name + --os-username + --os-user-domain-name + [--os-password ] + +If a password is not provided above (in plaintext), you will be interactively +prompted to provide one securely. + +Authentication may also be performed using an already-acquired token +and a URL pointing directly to the service API that presumably was acquired +from the Service Catalog:: + + export OS_TOKEN= + export OS_URL= + +The corresponding command-line options look very similar:: + + --os-token + --os-url + +In addition to that a regular `clouds.yaml` configuration file can be used + + +Links +===== + +* `Issue Tracker `_ +* `Documentation `_ diff --git a/README.rst b/README.rst index 5310c6980..6cb67c283 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ -OpenTelekomCloud extensions -=========================== +OTC Extensions +============== .. image:: https://travis-ci.org/OpenTelekomCloud/python-otcextensions.svg?branch=master :target: https://travis-ci.org/OpenTelekomCloud/python-otcextensions @@ -8,89 +8,70 @@ OpenTelekomCloud extensions :target: http://python-otcextensions.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status -OTCExtensions is a project to bring OTC extensions into the native OpenStack -toolstack. Covered are currently following items: +The OTC Extensions augment the OpenStack SDK of features and services +provided by the Open Telekom Cloud. If installed as a Python package, +they add several extra commands to the OpenStack Client CLI. Therefore +the project interacts closely with the * `python-openstacksdk` * `python-openstackclient` -The primary goal is to provide a possibility to use native OpenStack SDK and -CLI with the OTC additional services +packages. -Getting Started -=============== -The very first step to get started is to install otcextensions into your -system. For this please follow installation instructions_ +Installation +------------ -.. _instructions: http://python-otcextensions.readthedocs.io/en/latest/install/index.html +The OTC Extensions are hosted as the package `otcextensions` on PyPI +and can be installed by pip as -Next step would be logically configuration +.. code-block: console + $ pip install otcextensions -Configuration -============= - -openstack.config -================ - -The recommended way, since it is the most efficient way to configure both SDK -and the CLI in one place - -``openstack.config`` will find cloud configuration for as few as 1 clouds and -as many as you want to put in a config file. It will read environment variables -and config files, and it also contains some vendor specific default values so -that you don't have to know extra info to use OpenStack - -* If you have a config file, you will get the clouds listed in it -* If you have environment variables, you will get a cloud named `envvars` -* If you have neither, you will get a cloud named `defaults` with base defaults - -Sometimes an example is nice. - -Create a ``clouds.yaml`` file: - -.. code-block:: yaml - - clouds: - otc: - auth: - username: 'USER_NAME' - password: 'PASS' - 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 # !Important - ak: 'AK_VALUE' # AK/SK pair for access to OBS - sk: 'SK_VALUE' - -Please note: ``openstack.config`` will look for a file called ``clouds.yaml`` -in the following locations: - -* Current Directory -* ``~/.config/openstack`` -* ``/etc/openstack`` - -AK/SK values required for access to some services (i.e. OBS) can be either -configured as shown above in the clouds.yaml/secure.yaml, or they can be -automatically retrieved from the S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY. -Values from the clouds.yaml/secure.yaml take precedence over the ones from -environment. - -With this configuration you can start using openstackCLI simply ``openstack ---os-cloud otc`` +There are several options to do that including but not limited to pip +userland installation, system wide installation as well as +installation from operating system packets or directly from +source. Refer to the installation instructions_ in the projects +documentation. -More information at https://developer.openstack.org/sdks/python/openstacksdk/users/config -Old style way -============= - -The CLI can be configured via environment variables and command-line options as -listed in -https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html -or https://developer.openstack.org/sdks/python/openstacksdk/users/config. - -Authentication using username/password is often used:: +Configuration +------------- + +Acessing the Open Telekom Cloud APIs requires authentication and +authorization. For both there are several options available: + +* **Configuration files** (recommended): A file called `clouds.yaml` + holds all necessary configuration parameters. The file can be placed + either in the local directory, below the user home directory in + `.config/openstack` or in the system-wide directory + `/etc/openstack`. You may use a second file `secure.yaml` in the + same directories to extra protect clear-text password + credentials. For more details see the section `configuration`_ in + the official documentation. + + Minimal sample ``clouds.yaml`` file: + + .. code-block:: yaml + + clouds: + 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*" + + 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: export OS_AUTH_URL= export OS_IDENTITY_API_VERSION=3 @@ -102,7 +83,8 @@ Authentication using username/password is often used:: export S3_ACCESS_KEY_ID= export S3_SECRET_ACCESS_KEY= -The corresponding command-line options look very similar:: + +* **Command-Line Options:** The corresponding command-line options look very similar:: --os-auth-url --os-identity-api-version 3 @@ -112,12 +94,12 @@ The corresponding command-line options look very similar:: --os-user-domain-name [--os-password ] -If a password is not provided above (in plaintext), you will be interactively -prompted to provide one securely. + If a password is not provided above (in plaintext), you will be + interactively prompted to provide one securely. -Authentication may also be performed using an already-acquired token -and a URL pointing directly to the service API that presumably was acquired -from the Service Catalog:: +* **Existing Token:** Authentication may also be performed using an + already-acquired token and a URL pointing directly to the service + API that presumably was acquired from the Service Catalog:: export OS_TOKEN= export OS_URL= @@ -129,9 +111,27 @@ The corresponding command-line options look very similar:: In addition to that a regular `clouds.yaml` configuration file can be used +More information is available at +https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html +or +https://developer.openstack.org/sdks/python/openstacksdk/users/config + + +Writing Own Code +---------------- + +XXX Example XXXX + +Contributing +------------ + +See CONTRIBUTING.rst Links ===== * `Issue Tracker `_ * `Documentation `_ + +.. _instructions: http://python-otcextensions.readthedocs.io/en/latest/install/ + diff --git a/doc/source/contributor/coding.rst b/doc/source/contributor/coding.rst index bf76efb5d..0cbd7982c 100644 --- a/doc/source/contributor/coding.rst +++ b/doc/source/contributor/coding.rst @@ -1,113 +1,148 @@ -======================================== OpenStack SDK Developer Coding Standards ======================================== -In the beginning, there were no guidelines. And it was good. But that -didn't last long. As more and more people added more and more code, -we realized that we needed a set of coding standards to make sure that -the openstacksdk API at least *attempted* to display some form of consistency. +We follow the coding guidelines of +https://docs.openstack.org/hacking/latest/ of the OpenStack project in +general and the adopt the special rules of the OpenStack SDk in +specific where applicable unless otherwise stated. + +The SDK project which the OTC Extensions augment developed a set of +coding standards and guidelines were developed. Note that not all code +of OTC Extensions adheres to these standards just yet. All new code +has to adhere to these guidelines. -Thus, these coding standards/guidelines were developed. Note that not -all of openstacksdk adheres to these standards just yet. Some older code has -not been updated because we need to maintain backward compatibility. -Some of it just hasn't been changed yet. But be clear, all new code -*must* adhere to these guidelines. +Below are the patterns and principles that we expect developers to +follow. -Below are the patterns that we expect openstacksdk developers to follow. Release Notes -============= +------------- -openstacksdk uses `reno `_ for -managing its release notes. A new release note should be added to +OTC Extensions use `reno `_ +for managing its release notes. A new release note should be added to your contribution anytime you add new API calls, fix significant bugs, add new functionality or parameters to existing API calls, or make any -other significant changes to the code base that we should draw attention -to for the user base. +other significant changes to the code base that we should draw +attention to for the user base. + +It is not necessary to add release notes for minor fixes, such as +correction of documentation typos, minor code cleanup or +reorganization, or any other change that a user would not notice +through normal usage. -It is *not* necessary to add release notes for minor fixes, such as -correction of documentation typos, minor code cleanup or reorganization, -or any other change that a user would not notice through normal usage. Exceptions -========== +---------- -Exceptions should NEVER be wrapped and re-raised inside of a new exception. -This removes important debug information from the user. All of the exceptions -should be raised correctly the first time. +Exceptions should never be wrapped and re-raised inside of a new +exception. This removes important debug information from the +user. All of the exceptions should be raised correctly the first time. -openstack.cloud API Methods -=========================== + +API Methods of ``openstack.cloud`` +----------------------------------- The `openstack.cloud` layer has some specific rules: -- When an API call acts on a resource that has both a unique ID and a +* When an API call acts on a resource that has both a unique ID and a name, that API call should accept either identifier with a name_or_id parameter. -- All resources should adhere to the get/list/search interface that +* All resources should adhere to the get/list/search interface that control retrieval of those resources. E.g., `get_image()`, `list_images()`, `search_images()`. -- Resources should have `create_RESOURCE()`, `delete_RESOURCE()`, +* Resources should have `create_RESOURCE()`, `delete_RESOURCE()`, `update_RESOURCE()` API methods (as it makes sense). -- For those methods that should behave differently for omitted or None-valued +* For those methods that should behave differently for omitted or None-valued parameters, use the `_utils.valid_kwargs` decorator. Notably: all Neutron `update_*` functions. -- Deleting a resource should return True if the delete succeeded, or False +* Deleting a resource should return True if the delete succeeded, or False if the resource was not found. + Returned Resources ------------------ -Complex objects returned to the caller must be a `munch.Munch` type. The -`openstack._adapter.ShadeAdapter` class makes resources into `munch.Munch`. +Complex objects returned to the caller must be a `munch.Munch` +type. The `openstack._adapter.ShadeAdapter` class makes resources into +`munch.Munch`. -All objects should be normalized. It is shade's purpose in life to make -OpenStack consistent for end users, and this means not trusting the clouds -to return consistent objects. There should be a normalize function in -`openstack/cloud/_normalize.py` that is applied to objects before returning -them to the user. +All objects should be normalized. It is shade's purpose in life to +make OpenStack consistent for end users, and this means not trusting +the clouds to return consistent objects. There should be a normalize +function in `openstack/cloud/_normalize.py` that is applied to objects +before returning them to the user. -Fields should not be in the normalization contract if we cannot commit to -providing them to all users. +Fields should not be in the normalization contract if we cannot commit +to providing them to all users. -Fields should be renamed in normalization to be consistent with -the rest of `openstack.cloud`. For instance, nothing in `openstack.cloud` -exposes the legacy OpenStack concept of "tenant" to a user, but instead uses -"project" even if the cloud in question uses tenant. +Fields should be renamed in normalization to be consistent with the +rest of `openstack.cloud`. For instance, nothing in `openstack.cloud` +exposes the legacy OpenStack concept of "tenant" to a user, but +instead uses "project" even if the cloud in question uses tenant. -Nova vs. Neutron ----------------- - -- Recognize that not all cloud providers support Neutron, so never - assume it will be present. If a task can be handled by either - Neutron or Nova, code it to be handled by either. - -- For methods that accept either a Nova pool or Neutron network, the - parameter should just refer to the network, but documentation of it - should explain about the pool. See: `create_floating_ip()` and - `available_floating_ip()` methods. Tests -===== +----- -- New API methods *must* have unit tests! +* New API methods must have unit tests. -- New unit tests should only mock at the REST layer using `requests_mock`. +* New unit tests should only mock at the REST layer using `requests_mock`. Any mocking of openstacksdk itself should be considered legacy and to be avoided. Exceptions to this rule can be made when attempting to test the internals of a logical shim where the inputs and output of the method aren't actually impacted by remote content. -- Functional tests should be added, when possible. +* Functional tests should be added, when possible. -- In functional tests, always use unique names (for resources that have this +* In functional tests, always use unique names (for resources that have this attribute) and use it for clean up (see next point). -- In functional tests, always define cleanup functions to delete data added +* In functional tests, always define cleanup functions to delete data added by your test, should something go wrong. Data removal should be wrapped in a try except block and try to delete as many entries added by the test as possible. + + +Docstrings +---------- + +Docstrings should only use triple-double-quotes (``"""``). + +Single-line docstrings should never have extraneous whitespace +between enclosing triple-double-quotes. + +Sentence fragments do not have punctuation. Specifically in the +command classes the one line docstring is also the help string for +that command and those do not have periods. + + """A one line docstring looks like this""" + + +Calling Methods +--------------- + +When breaking up method calls due to the 79 char line length limit, +use the alternate four space indent. With the first argument on the +succeeding line all arguments will then be vertically aligned. Use the +same convention used with other data structure literals and terminate +the method call with the last argument line ending with a comma and +the closing paren on its own line indented to the starting line level. + +.. code-block: python + unnecessarily_long_function_name( + 'string one', + 'string two', + kwarg1=constants.ACTIVE, + kwarg2=['a', 'b', 'c'], + ) + + +Python 3 Compatibility +---------------------- + +The OTC Extensions are developed for Python 3. Compatibility for +Python 2.7 might be present, but would be so on accident. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 360d515a5..f66736122 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,17 +1,18 @@ Contributing to the OTC Extensions ================================== -This section of documentation pertains to those who wish to contribute to the -development of this project. If you're looking for documentation on how to use -the SDK to build applications, please see the `sdk <../sdk>`_ section. +This section of the documentation is intended for those who want to +contribute to the development of the OTC Extensions. If you're looking +for documentation on how to use the SDK to build applications, please +see the `SDK <../sdk>`_ section. -Setting up Development Environment ----------------------------------- +Setting up an Development Environment +------------------------------------- -The first step towards contributing code and documentation is to setup your -development environment. We use a pretty standard setup, but it is fully -documented in our :doc:`setup ` section. +The first step towards contributing code and documentation is to setup +your development environment. The project implements a pretty standard +setup. It is fully documented in the :doc:`setup ` section. .. toctree:: :maxdepth: 2 @@ -37,8 +38,9 @@ created services such as ``Cloud Container Engine (CCE)`` are hosted. Coding Standards ---------------- -We are a bit stricter than usual in the coding standards department. It's a -good idea to read through the :doc:`coding ` section. +We are a bit stricter than usual in the coding standards +department. It's a good idea to read through the :doc:`coding +` section. .. toctree:: :maxdepth: 2 @@ -50,24 +52,24 @@ Testing ------- The project contains three test packages, one for unit tests, one for -functional tests and one for examples tests. The ``openstack.tests.unit`` -package tests the SDK's features in isolation. The -``openstack.tests.functional`` and ``openstack.tests.examples`` packages test -the SDK's features and examples against an OpenStack cloud. +functional tests and one for examples tests. The +``openstack.tests.unit`` package tests the SDK's features in +isolation. The ``openstack.tests.functional`` and +``openstack.tests.examples`` packages test the SDK's features and +examples against an OpenStack cloud. .. toctree:: testing - Example SDK Service and Resource Implementation ----------------------------------------------- -Does this SDK not do what you need it to do? Is it missing a service? Are you -a developer on another project who wants to add their service? You're in the -right place. Below are examples of how to add new features to the -OpenStack SDK. +Do the OTC Extensions not do what you need them to do? Are they +missing a service? Are you a developer on another project who wants to +add a service? You're in the right place. Below are examples of how to +add new features to the project. .. toctree:: :maxdepth: 2 @@ -79,6 +81,6 @@ Contacting the OTC Extensions Developers ---------------------------------------- Currently no official communication other than `GitHub -`_ is available. -Feel free to open new issues if you want to contact us directly or have -questions related to the existent packages. +`_ is +available. Feel free to open new issues if you want to contact us +directly or have questions related to the existent packages. From 15abd039b5fab330b04fc4c6c1bdefb902ef0aec Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 20 Mar 2020 11:08:48 +0000 Subject: [PATCH 26/42] Finished Auto-Scaling SDK guide and pep8 fixes --- README.rst | 8 +- doc/source/contributor/coding.rst | 2 +- doc/source/sdk/guides/auto_scaling.rst | 243 ++++++++++++++++-- .../auto_scaling/batch_instance_action.py | 37 +++ examples/auto_scaling/delete_group.py | 23 ++ examples/auto_scaling/delete_policy.py | 23 ++ examples/auto_scaling/execute_policy.py | 25 ++ examples/auto_scaling/find_config.py | 2 +- examples/auto_scaling/find_group.py | 24 ++ examples/auto_scaling/find_policy.py | 24 ++ examples/auto_scaling/get_group.py | 24 ++ examples/auto_scaling/get_policy.py | 24 ++ examples/auto_scaling/list_activities.py | 27 ++ examples/auto_scaling/list_instances.py | 25 ++ examples/auto_scaling/list_policies.py | 25 ++ examples/auto_scaling/list_quotas.py | 27 ++ examples/auto_scaling/pause_group.py | 25 ++ examples/auto_scaling/pause_policy.py | 25 ++ examples/auto_scaling/remove_instance.py | 26 ++ examples/auto_scaling/resume_group.py | 24 ++ examples/auto_scaling/resume_policy.py | 25 ++ examples/auto_scaling/update_policy.py | 39 +++ 22 files changed, 705 insertions(+), 22 deletions(-) create mode 100644 examples/auto_scaling/batch_instance_action.py create mode 100644 examples/auto_scaling/delete_group.py create mode 100644 examples/auto_scaling/delete_policy.py create mode 100644 examples/auto_scaling/execute_policy.py create mode 100644 examples/auto_scaling/find_group.py create mode 100644 examples/auto_scaling/find_policy.py create mode 100644 examples/auto_scaling/get_group.py create mode 100644 examples/auto_scaling/get_policy.py create mode 100644 examples/auto_scaling/list_activities.py create mode 100644 examples/auto_scaling/list_instances.py create mode 100644 examples/auto_scaling/list_policies.py create mode 100644 examples/auto_scaling/list_quotas.py create mode 100644 examples/auto_scaling/pause_group.py create mode 100644 examples/auto_scaling/pause_policy.py create mode 100644 examples/auto_scaling/remove_instance.py create mode 100644 examples/auto_scaling/resume_group.py create mode 100644 examples/auto_scaling/resume_policy.py create mode 100644 examples/auto_scaling/update_policy.py diff --git a/README.rst b/README.rst index 6cb67c283..cc2d97920 100644 --- a/README.rst +++ b/README.rst @@ -71,7 +71,8 @@ authorization. For both there are several options available: --os-cloud otc *command*`` or by ``export OS_CLOUD=otc; openstack *command*``. -* **Environment variables:** Authentication using username/password is often used: +* **Environment variables:** Authentication using username/password is often + used: export OS_AUTH_URL= export OS_IDENTITY_API_VERSION=3 @@ -83,8 +84,9 @@ 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:: + +* **Command-Line Options:** The corresponding command-line options look + very similar:: --os-auth-url --os-identity-api-version 3 diff --git a/doc/source/contributor/coding.rst b/doc/source/contributor/coding.rst index 0cbd7982c..2689807e5 100644 --- a/doc/source/contributor/coding.rst +++ b/doc/source/contributor/coding.rst @@ -39,7 +39,7 @@ exception. This removes important debug information from the user. All of the exceptions should be raised correctly the first time. -API Methods of ``openstack.cloud`` +API Methods of ``openstack.cloud`` ----------------------------------- The `openstack.cloud` layer has some specific rules: diff --git a/doc/source/sdk/guides/auto_scaling.rst b/doc/source/sdk/guides/auto_scaling.rst index a9ca7a412..fbf617e79 100644 --- a/doc/source/sdk/guides/auto_scaling.rst +++ b/doc/source/sdk/guides/auto_scaling.rst @@ -13,8 +13,8 @@ the AS group. The AS configuration is decoupled from the AS group and can be used several times in different groups. Up to 100 AS configurations can be created for each user. -List Auto-Scaling Configurations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +List Configurations +^^^^^^^^^^^^^^^^^^^ This interface is used to query all Auto-Scaling configurations and to filter the output with query parameters. @@ -22,8 +22,8 @@ the output with query parameters. .. literalinclude:: ../examples/auto_scaling/list_configs.py :lines: 16-22 -Create Auto-Scaling Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Create Configuration +^^^^^^^^^^^^^^^^^^^^ This interface is used to create an Auto-Scaling Configuration instance with parameters. @@ -31,17 +31,18 @@ parameters. .. literalinclude:: ../examples/auto_scaling/create_config.py :lines: 16-36 -Get Auto-Scaling Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Get Configuration +^^^^^^^^^^^^^^^^^ This interface is used to get an Auto-Scaling Configuration by ID -or an instance of :class:`~otcextensions.sdk.auto_scaling.v1.config.Config`. +or an instance of class +:class:`~otcextensions.sdk.auto_scaling.v1.config.Config`. .. literalinclude:: ../examples/auto_scaling/get_config.py :lines: 16-24 -Find Auto-Scaling Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Find Configuration +^^^^^^^^^^^^^^^^^^ This interface is used to find an Auto-Scaling Configuration instance by name or id. @@ -49,21 +50,22 @@ name or id. .. literalinclude:: ../examples/auto_scaling/find_config.py :lines: 16-24 -Delete Auto-Scaling Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Delete Configuration +^^^^^^^^^^^^^^^^^^^^ This interface is used to delete an Auto-Scaling Configuration instance by id -or an instance of :class:`~otcextensions.sdk.auto_scaling.v1.config.Config`. +or an instance of class +:class:`~otcextensions.sdk.auto_scaling.v1.config.Config`. .. literalinclude:: ../examples/auto_scaling/delete_config.py :lines: 16-23 -Batch Delete Auto-Scaling Configurations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Batch Delete Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^^^ This interface is used to delete multiple Auto-Scaling Configuration instances by id or an instance of -:class:`~otcextensions.sdk.auto_scaling.v1.config.Config`. +class :class:`~otcextensions.sdk.auto_scaling.v1.config.Config`. .. literalinclude:: ../examples/auto_scaling/batch_delete_config.py :lines: 16-26 @@ -78,11 +80,218 @@ maximum number of instances, expected number of instances, minimum number of instances, VPC, subnet, and load balancing. Each user can create a maximum of 25 AS groups by default. -List Auto-Scaling Groups -^^^^^^^^^^^^^^^^^^^^^^^^ +List Groups +^^^^^^^^^^^ This interface is used to query all Auto-Scaling Groups and to filter the output with query parameters. .. literalinclude:: ../examples/auto_scaling/list_groups.py :lines: 16-22 + +Create Group +^^^^^^^^^^^^ + +This interface is used to create an Auto-Scaling Group with parameters. + +**NEEDS TO BE DONE** + +Get Group +^^^^^^^^^ + +This interface is used to get an Auto-Scaling Group by ID +or an instance of class +:class:`~otcextensions.sdk.auto_scaling.v1.group.Group`. + +.. literalinclude:: ../examples/auto_scaling/get_group.py + :lines: 16-24 + +Find Group +^^^^^^^^^^ + +This interface is used to find an Auto-Scaling Group instance by +name or id. + +.. literalinclude:: ../examples/auto_scaling/find_group.py + :lines: 16-24 + +Delete Group +^^^^^^^^^^^^ + +This interface is used to delete an Auto-Scaling Group instance by id or +an instance of class :class:`~otcextensions.sdk.auto_scaling.v1.group.Group`. + +.. literalinclude:: ../examples/auto_scaling/delete_group.py + :lines: 16-23 + +Pause Group +^^^^^^^^^^^ + +This interface is used to pause an Auto-Scaling Group instance in +passive state by using id or an instance of +class :class:`~otcextensions.sdk.auto_scaling.v1.group.Group`. + +.. literalinclude:: ../examples/auto_scaling/pause_group.py + :lines: 16-25 + +Resume Group +^^^^^^^^^^^^ + +This interface is used to resume an Auto-Scaling Group instance in +active state by using id or an instance of +class :class:`~otcextensions.sdk.auto_scaling.v1.group.Group`. + +.. literalinclude:: ../examples/auto_scaling/resume_group.py + :lines: 16-24 + +Auto-Scaling Policy +------------------- + +An Auto-Scaling (AS) policy defines whether to increase or decrease the number +of instances in an AS group. If the number and the expected number of +instances in an AS group are different due to the execution of the AS policy, +AS automatically adjusts the number of instances to the expected. AS supports +the following policy variants: + +* alarm-triggered policy +* periodic policy +* scheduled policy + +List Policy +^^^^^^^^^^^ + +This interface is used to query all Auto-Scaling Policies of an AS group +and to filter the output with query parameters. + +.. literalinclude:: ../examples/auto_scaling/list_policies.py + :lines: 16-25 + +Create Policy +^^^^^^^^^^^^^ + +This interface is used to create an Auto-Scaling Policy with parameters. + +**NEEDS TO BE DONE** + +Get Policy +^^^^^^^^^^ + +This interface is used to get an Auto-Scaling Policy by ID +or an instance of class +:class:`~otcextensions.sdk.auto_scaling.v1.policy.Policy`. + +.. literalinclude:: ../examples/auto_scaling/get_policy.py + :lines: 16-24 + +Find Policy +^^^^^^^^^^^ + +This interface is used to find an Auto-Scaling Policy instance by +name or id. + +.. literalinclude:: ../examples/auto_scaling/find_policy.py + :lines: 16-24 + +Delete Policy +^^^^^^^^^^^^^ + +This interface is used to delete an Auto-Scaling Policy instance by id +or an instance of class +:class:`~otcextensions.sdk.auto_scaling.v1.policy.Policy`. + +.. literalinclude:: ../examples/auto_scaling/delete_policy.py + :lines: 16-23 + +Update Policy +^^^^^^^^^^^^^ + +This interface is used to update an Auto-Scaling Policy instance by +using policy's id or an instance of class +:class:`~otcextensions.sdk.auto_scaling.v1.policy.Policy` and provide new +attributes. + +.. literalinclude:: ../examples/auto_scaling/update_policy.py + :lines: 16-39 + +Pause Policy +^^^^^^^^^^^^ + +This interface is used to pause an Auto-Scaling Policy instance in +passive state by using id or an instance of +class :class:`~otcextensions.sdk.auto_scaling.v1.policy.Policy`. + +.. literalinclude:: ../examples/auto_scaling/pause_policy.py + :lines: 16-25 + +Resume Policy +^^^^^^^^^^^^^ + +This interface is used to resume an Auto-Scaling Policy instance in +active state by using id or an instance of +class :class:`~otcextensions.sdk.auto_scaling.v1.policy.Policy`. + +.. literalinclude:: ../examples/auto_scaling/resume_policy.py + :lines: 16-25 + +Execute Policy +^^^^^^^^^^^^^^ + +This interface is used to execute an Auto-Scaling Policy instance and +run the defined actions. + +.. literalinclude:: ../examples/auto_scaling/execute_policy.py + :lines: 16-25 + +Auto-Scaling Instance +--------------------- + +An Auto-Scaling (AS) Instance is the executive unit of an Auto-Scaling group. + +List Instances +^^^^^^^^^^^^^^ + +This interface is used to query all Auto-Scaling Instances of an AS group +and to filter the output with query parameters. + +.. literalinclude:: ../examples/auto_scaling/list_instances.py + :lines: 16-25 + +Remove Instance +^^^^^^^^^^^^^^^ + +This interface is used to remove an Auto-Scaling Instances of an AS group. + +.. literalinclude:: ../examples/auto_scaling/remove_instance.py + :lines: 16-26 + +Batch Action Instance +^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to run actions on an Auto-Scaling group by adding +or deleting instance. + +.. literalinclude:: ../examples/auto_scaling/batch_instance_action.py + :lines: 16-37 + +Auto-Scaling Actions and Quotas +------------------------------- + +Auto-Scaling quotas and query scaling action logs can be querried. + +List Scaling Actions +^^^^^^^^^^^^^^^^^^^^ + +This interface is used to query all Auto-Scaling scaling action logs +of an AS group and to filter the output with query parameters. + +.. literalinclude:: ../examples/auto_scaling/list_activities.py + :lines: 16-27 + +List User or Group Quota for Auto-Scaling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to query all Auto-Scaling quotas of an AS group +or a user and to filter the output with query parameters. + +.. literalinclude:: ../examples/auto_scaling/list_quotas.py + :lines: 16-27 diff --git a/examples/auto_scaling/batch_instance_action.py b/examples/auto_scaling/batch_instance_action.py new file mode 100644 index 000000000..7b6d44adf --- /dev/null +++ b/examples/auto_scaling/batch_instance_action.py @@ -0,0 +1,37 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Remove an Auto-Scaling Instances of a specific AS Group. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +group = "group_name_or_id" +group = conn.auto_scaling.find_group(group) + +instances = [ + "instance_id", + "instance_id2" +] + +action = "ADD" + +conn.auto_scaling.batch_instance_action( + group, + instances, + action, # ADD, REMOVE, PROTECT, UNPROTECT + delete_instance=False +) diff --git a/examples/auto_scaling/delete_group.py b/examples/auto_scaling/delete_group.py new file mode 100644 index 000000000..49c362334 --- /dev/null +++ b/examples/auto_scaling/delete_group.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Delete Auto-Scaling Group by id or instance of class Group. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +group_id = '1234567-ad7a-48ce-8f92-b55c651439d2' +conn.auto_scaling.delete_group(group_id) diff --git a/examples/auto_scaling/delete_policy.py b/examples/auto_scaling/delete_policy.py new file mode 100644 index 000000000..84891947d --- /dev/null +++ b/examples/auto_scaling/delete_policy.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Delete Auto-Scaling Policy by id or instance of class Policy. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +policy_id = '1234567-ad7a-48ce-8f92-b55c651439d2' +conn.auto_scaling.delete_policy(policy_id) diff --git a/examples/auto_scaling/execute_policy.py b/examples/auto_scaling/execute_policy.py new file mode 100644 index 000000000..f90d78b2d --- /dev/null +++ b/examples/auto_scaling/execute_policy.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Execute an Auto-Scaling Policy by id or an instance of class Policy +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +policy = "policy_name_or_id" +policy = conn.auto_scaling.find_policy(policy) + +conn.auto_scaling.execute_policy(policy) diff --git a/examples/auto_scaling/find_config.py b/examples/auto_scaling/find_config.py index 177fc6e4f..36969af62 100644 --- a/examples/auto_scaling/find_config.py +++ b/examples/auto_scaling/find_config.py @@ -11,7 +11,7 @@ # License for the specific language governing permissions and limitations # under the License. """ -Find Auto-Scaling Configuration. +Find Auto-Scaling Configuration by name or id. """ import openstack diff --git a/examples/auto_scaling/find_group.py b/examples/auto_scaling/find_group.py new file mode 100644 index 000000000..38bc88d9c --- /dev/null +++ b/examples/auto_scaling/find_group.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Find Auto-Scaling Group. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +group = "group_name_or_id" + +group = conn.auto_scaling.find_group(group) +print(group) diff --git a/examples/auto_scaling/find_policy.py b/examples/auto_scaling/find_policy.py new file mode 100644 index 000000000..4d33596cd --- /dev/null +++ b/examples/auto_scaling/find_policy.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Find Auto-Scaling Policy by name or id. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +policy = "policy_name_or_id" + +policy = conn.auto_scaling.find_policy(policy) +print(policy) diff --git a/examples/auto_scaling/get_group.py b/examples/auto_scaling/get_group.py new file mode 100644 index 000000000..7a884ae90 --- /dev/null +++ b/examples/auto_scaling/get_group.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get Auto-Scaling Group by id or object +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +group_id = "1234567-6aa0-4c8b-b350-3bd937addeb7" +group = conn.auto_scaling.get_group(group_id) +print(group) diff --git a/examples/auto_scaling/get_policy.py b/examples/auto_scaling/get_policy.py new file mode 100644 index 000000000..f3673b16c --- /dev/null +++ b/examples/auto_scaling/get_policy.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get Auto-Scaling Policy by id or object +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +policy_id = "1234567-6aa0-4c8b-b350-3bd937addeb7" +policy = conn.auto_scaling.get_policy(policy_id) +print(policy) diff --git a/examples/auto_scaling/list_activities.py b/examples/auto_scaling/list_activities.py new file mode 100644 index 000000000..eafd7f50d --- /dev/null +++ b/examples/auto_scaling/list_activities.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List all Auto-Scaling query action logs of an AS group. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +group = "group_name_or_id" +group = conn.auto_scaling.find_group(group) + + +for activity in conn.auto_scaling.activities(group): + print(activity) diff --git a/examples/auto_scaling/list_instances.py b/examples/auto_scaling/list_instances.py new file mode 100644 index 000000000..d766d31a9 --- /dev/null +++ b/examples/auto_scaling/list_instances.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List all Auto-Scaling scaling action logs of a specific AS Group. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +group = "group_name_or_id" +group = conn.auto_scaling.find_group(group) + +for activity in conn.auto_scaling.activities(group): + print(activity) diff --git a/examples/auto_scaling/list_policies.py b/examples/auto_scaling/list_policies.py new file mode 100644 index 000000000..25e5b7ba8 --- /dev/null +++ b/examples/auto_scaling/list_policies.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List all Auto-Scaling Policies of a specific AS Group. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +group = "group_name_or_id" +group = conn.auto_scaling.find_group(group) + +for policy in conn.auto_scaling.policies(group): + print(policy) diff --git a/examples/auto_scaling/list_quotas.py b/examples/auto_scaling/list_quotas.py new file mode 100644 index 000000000..098b3b628 --- /dev/null +++ b/examples/auto_scaling/list_quotas.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List all Auto-Scaling quotas of a user or a specific AS Group. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +# group = "group_name_or_id" +# group = conn.auto_scaling.find_group(group) + +# If group is set, group quotas ar listed instead of user quotas +for quota in conn.auto_scaling.quotas(group=None): + print(quota) diff --git a/examples/auto_scaling/pause_group.py b/examples/auto_scaling/pause_group.py new file mode 100644 index 000000000..7b4499e97 --- /dev/null +++ b/examples/auto_scaling/pause_group.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Pause an Auto-Scaling Group by id or an instance of class Group +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +group = "group_name_or_id" +group = conn.auto_scaling.find_group(group) + +conn.auto_scaling.pause_group(group) diff --git a/examples/auto_scaling/pause_policy.py b/examples/auto_scaling/pause_policy.py new file mode 100644 index 000000000..fcf0a715c --- /dev/null +++ b/examples/auto_scaling/pause_policy.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Pause an Auto-Scaling Policy by id or an instance of class Policy +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +policy = "policy_name_or_id" +policy = conn.auto_scaling.find_policy(policy) + +conn.auto_scaling.pause_policy(policy) diff --git a/examples/auto_scaling/remove_instance.py b/examples/auto_scaling/remove_instance.py new file mode 100644 index 000000000..4ada6aa39 --- /dev/null +++ b/examples/auto_scaling/remove_instance.py @@ -0,0 +1,26 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Remove an Auto-Scaling Instances of a specific AS Group. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +instance = "instance_id" + +conn.auto_scaling.remove_instance( + instance, + delete=False # If True, instance will be deleted after remove +) diff --git a/examples/auto_scaling/resume_group.py b/examples/auto_scaling/resume_group.py new file mode 100644 index 000000000..559d6940f --- /dev/null +++ b/examples/auto_scaling/resume_group.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Resume an Auto-Scaling Group by id or an instance of class Group +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +group_id = "123456_group_id" + +conn.auto_scaling.resume_group(group_id) diff --git a/examples/auto_scaling/resume_policy.py b/examples/auto_scaling/resume_policy.py new file mode 100644 index 000000000..b740a55dc --- /dev/null +++ b/examples/auto_scaling/resume_policy.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Resume an Auto-Scaling Policy by id or an instance of class Policy +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +policy = "policy_name_or_id" +policy = conn.auto_scaling.find_policy(policy) + +conn.auto_scaling.resume_policy(policy) diff --git a/examples/auto_scaling/update_policy.py b/examples/auto_scaling/update_policy.py new file mode 100644 index 000000000..4ef87e2d6 --- /dev/null +++ b/examples/auto_scaling/update_policy.py @@ -0,0 +1,39 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Update Auto-Scaling Policy by using id or an instance of class Policy. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +policy = "policy_name_or_id" +attrs = { + "scaling_policy_type": "RECURRENCE", + "scaling_policy_name": "policy_01", + "scheduled_policy": { + "launch_time": "16:00", + "recurrence_type": "Daily", + "end_time": "2016-02-08T17:31Z", + "start_time": "2016-01-08T17:31Z" + }, + "scaling_policy_action": { + "operation": "SET", + "instance_number": 2 + } +} + +policy = conn.auto_scaling.find_policy(policy) +conn.auto_scaling.update_policy(policy, **attrs) From fb67450fc03de77817cd39529e939d0b5c123c86 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 20 Mar 2020 13:14:16 +0000 Subject: [PATCH 27/42] Anti-DDoS SDK guide status draft --- doc/source/sdk/guides/anti_ddos.rst | 52 +++++++++++++++++++ doc/source/sdk/guides/index.rst | 1 + .../anti_ddos/get_floating_ip_policies.py | 25 +++++++++ examples/anti_ddos/list_floating_ips.py | 23 ++++++++ examples/anti_ddos/protect_floating_ip.py | 23 ++++++++ examples/anti_ddos/unprotect_floating_ip.py | 23 ++++++++ 6 files changed, 147 insertions(+) create mode 100644 doc/source/sdk/guides/anti_ddos.rst create mode 100644 examples/anti_ddos/get_floating_ip_policies.py create mode 100644 examples/anti_ddos/list_floating_ips.py create mode 100644 examples/anti_ddos/protect_floating_ip.py create mode 100644 examples/anti_ddos/unprotect_floating_ip.py diff --git a/doc/source/sdk/guides/anti_ddos.rst b/doc/source/sdk/guides/anti_ddos.rst new file mode 100644 index 000000000..bc34b756f --- /dev/null +++ b/doc/source/sdk/guides/anti_ddos.rst @@ -0,0 +1,52 @@ +Anti-DDoS (AS) +============== + +.. contents:: Table of Contents + :local: + +Floating-IP Operations +---------------------- + +Floating IP operations lists all methods which are used to query and modify +Floating IPs settings related to Anti-DDoS. + +List Anti-DDoS Floating IPs +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to query all Floating IPs protected by Anti-DDoS and +limit the output with parameters. + +.. literalinclude:: ../examples/anti_ddos/list_floating_ips.py + :lines: 16-23 + +Protect an Floating IP (not working) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to enable Anti-DDoS on a Floating IP by using IP id or +an instance of class +:class:`~otcextensions.sdk.anti_ddos.v1.floating_ip.FloatingIP`. + +.. literalinclude:: ../examples/anti_ddos/protect_floating_ip.py + :lines: 17-23 + +Unprotect an Floating IP (not working) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to disable Anti-DDoS on a Floating IP by using IP id or +an instance of class +:class:`~otcextensions.sdk.anti_ddos.v1.floating_ip.FloatingIP`. + +.. literalinclude:: ../examples/anti_ddos/unprotect_floating_ip.py + :lines: 17-23 + +Get Policies of a Floating IP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This Interface is used to query the Anti-DDoS Policy for a specific Floating +IP by using Floating IP id or an instance of class +:class:`~otcextensions.sdk.anti_ddos.v1.floating_ip.FloatingIP`. Anti-DDoS +must be enabled for this IP otherwise an error occures. + +.. literalinclude:: ../examples/anti_ddos/get_floating_ip_policies.py + :lines: 18-25 + diff --git a/doc/source/sdk/guides/index.rst b/doc/source/sdk/guides/index.rst index 18433aa49..4229e6a27 100644 --- a/doc/source/sdk/guides/index.rst +++ b/doc/source/sdk/guides/index.rst @@ -7,6 +7,7 @@ Open Telekom Cloud related User Guides .. toctree:: :maxdepth: 1 + anti_ddos auto_scaling deh logging diff --git a/examples/anti_ddos/get_floating_ip_policies.py b/examples/anti_ddos/get_floating_ip_policies.py new file mode 100644 index 000000000..47d95405e --- /dev/null +++ b/examples/anti_ddos/get_floating_ip_policies.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Retrieve Anti-DDoS Policy for a specific Floating IP by using Floating IP id +or an instance of class FloatingIP. Anti-DDoS must be enabled for this IP +otherwise an error occures. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +fip = "floating_ip_id" +policy = conn.anti_ddos.get_floating_ip_policies(fip) +print(policy) diff --git a/examples/anti_ddos/list_floating_ips.py b/examples/anti_ddos/list_floating_ips.py new file mode 100644 index 000000000..7dfef4690 --- /dev/null +++ b/examples/anti_ddos/list_floating_ips.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List all Anti-DDoS Floating IPs and limit the output with query parameters. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +for fip in conn.anti_ddos.floating_ips(): + print(fip) diff --git a/examples/anti_ddos/protect_floating_ip.py b/examples/anti_ddos/protect_floating_ip.py new file mode 100644 index 000000000..bc158689f --- /dev/null +++ b/examples/anti_ddos/protect_floating_ip.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Protect with Anti-DDoS a Floating IP by using id or an instance of class +FloatingIP +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +fip = "floating_ip_id" +conn.anti_ddos.protect_floating_ip(fip) diff --git a/examples/anti_ddos/unprotect_floating_ip.py b/examples/anti_ddos/unprotect_floating_ip.py new file mode 100644 index 000000000..9d55dba19 --- /dev/null +++ b/examples/anti_ddos/unprotect_floating_ip.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Unprotect a Floating IP from Anti-DDoS by using id or an instance of class +FloatingIP +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +fip = "floating_ip_id" +conn.anti_ddos.unprotect_floating_ip(fip) From c18e10377bf6dd7b62e74b7042b4628291c2d5e8 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 20 Mar 2020 16:14:51 +0000 Subject: [PATCH 28/42] Finish Anti-DDoS SDK Guide --- doc/source/sdk/guides/anti_ddos.rst | 63 ++++++++++++++++++- examples/anti_ddos/get_floating_ip_status.py | 25 ++++++++ examples/anti_ddos/list_configs.py | 23 +++++++ examples/anti_ddos/list_floating_ip_events.py | 25 ++++++++ .../anti_ddos/list_floating_ip_stat_day.py | 25 ++++++++ .../anti_ddos/list_floating_ip_stat_week.py | 23 +++++++ .../anti_ddos/update_floating_ip_policies.py | 30 +++++++++ 7 files changed, 211 insertions(+), 3 deletions(-) create mode 100644 examples/anti_ddos/get_floating_ip_status.py create mode 100644 examples/anti_ddos/list_configs.py create mode 100644 examples/anti_ddos/list_floating_ip_events.py create mode 100644 examples/anti_ddos/list_floating_ip_stat_day.py create mode 100644 examples/anti_ddos/list_floating_ip_stat_week.py create mode 100644 examples/anti_ddos/update_floating_ip_policies.py diff --git a/doc/source/sdk/guides/anti_ddos.rst b/doc/source/sdk/guides/anti_ddos.rst index bc34b756f..28a82624a 100644 --- a/doc/source/sdk/guides/anti_ddos.rst +++ b/doc/source/sdk/guides/anti_ddos.rst @@ -39,14 +39,71 @@ an instance of class .. literalinclude:: ../examples/anti_ddos/unprotect_floating_ip.py :lines: 17-23 -Get Policies of a Floating IP -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Get Floating IP Policies +^^^^^^^^^^^^^^^^^^^^^^^^ This Interface is used to query the Anti-DDoS Policy for a specific Floating IP by using Floating IP id or an instance of class :class:`~otcextensions.sdk.anti_ddos.v1.floating_ip.FloatingIP`. Anti-DDoS -must be enabled for this IP otherwise an error occures. +must be enabled for the specific Floating IP otherwise an error occures. .. literalinclude:: ../examples/anti_ddos/get_floating_ip_policies.py :lines: 18-25 +Update Floating IP Policies +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This Interface is used to update Anti-DDoS Policy attributes. + +.. literalinclude:: ../examples/anti_ddos/update_floating_ip_policies.py + :lines: 16-30 + +Get Floating IP Status +^^^^^^^^^^^^^^^^^^^^^^ + +This Interface is used to query Anti-DDoS status of a Floating IP by using +id. + +.. literalinclude:: ../examples/anti_ddos/get_floating_ip_status.py + :lines: 16-25 + +List Floating IP Events +^^^^^^^^^^^^^^^^^^^^^^^ + +This Interface is used to query all Anti-DDoS events of a Floating IP by using +id. + +.. literalinclude:: ../examples/anti_ddos/list_floating_ip_events.py + :lines: 16-25 + +List Floating IP Day Statistics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This Interface is used to query all Anti-DDoS events per day of a Floating IP +by using id. + +.. literalinclude:: ../examples/anti_ddos/list_floating_ip_stat_day.py + :lines: 16-25 + +List Week Statistics of all Floating IPs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This Interface is used to query all Anti-DDoS events per week of all Floating +IPs. + +.. literalinclude:: ../examples/anti_ddos/list_floating_ip_stat_week.py + :lines: 16-23 + +Alarm Configuration +------------------- + +Anti-DDoS alerts can be sent in various ways and notifies in case of defense. + +List Alarm Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This Interface is used to query Anti-DDoS alarm configurations. + +.. literalinclude:: ../examples/anti_ddos/list_configs.py + :lines: 16-23 + diff --git a/examples/anti_ddos/get_floating_ip_status.py b/examples/anti_ddos/get_floating_ip_status.py new file mode 100644 index 000000000..41c3bc366 --- /dev/null +++ b/examples/anti_ddos/get_floating_ip_status.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get Anti-DDoS status of a Floating IP by using id. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +fip = "floating_ip_id" + +status = conn.anti_ddos.get_floating_ip_status(fip) +print(status) diff --git a/examples/anti_ddos/list_configs.py b/examples/anti_ddos/list_configs.py new file mode 100644 index 000000000..8ab079e63 --- /dev/null +++ b/examples/anti_ddos/list_configs.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List Anti-DDoS alarm configurations. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +for config in conn.anti_ddos.configs(): + print(config) diff --git a/examples/anti_ddos/list_floating_ip_events.py b/examples/anti_ddos/list_floating_ip_events.py new file mode 100644 index 000000000..a457fb70b --- /dev/null +++ b/examples/anti_ddos/list_floating_ip_events.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get Anti-DDoS status of a Floating IP by using id. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +fip = "floating_ip_id" + +for event in conn.anti_ddos.floating_ip_events(fip): + print(event) diff --git a/examples/anti_ddos/list_floating_ip_stat_day.py b/examples/anti_ddos/list_floating_ip_stat_day.py new file mode 100644 index 000000000..0d1c38124 --- /dev/null +++ b/examples/anti_ddos/list_floating_ip_stat_day.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List Anti-DDoS events per day of a Floating IP by using id. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +fip = "floating_ip_id" + +for event in conn.anti_ddos.floating_ip_stat_day(fip): + print(event) diff --git a/examples/anti_ddos/list_floating_ip_stat_week.py b/examples/anti_ddos/list_floating_ip_stat_week.py new file mode 100644 index 000000000..1ea2e70f1 --- /dev/null +++ b/examples/anti_ddos/list_floating_ip_stat_week.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List all Anti-DDoS events per week of all Floating IPs. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +for event in conn.anti_ddos.floating_ip_stat_week(): + print(event) diff --git a/examples/anti_ddos/update_floating_ip_policies.py b/examples/anti_ddos/update_floating_ip_policies.py new file mode 100644 index 000000000..2ab5f7634 --- /dev/null +++ b/examples/anti_ddos/update_floating_ip_policies.py @@ -0,0 +1,30 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Update Anti-DDoS Policy attributes. +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +fip = "floating_ip_id" +attrs = { + "enable_L7": False, + "traffic_pos_id": 2, + "http_request_pos_id": 1, + "cleaning_access_pos_id": 1, + "app_type_id": 1 +} + +policy = conn.anti_ddos.update_floating_ip_policies(fip, **attrs) From 35d4fae289493eadbb998df8705aa72e190193b0 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 20 Mar 2020 16:28:50 +0000 Subject: [PATCH 29/42] Update ZuuL config to test tox -e docs --- .zuul.yaml | 34 ++++++---------------------------- 1 file changed, 6 insertions(+), 28 deletions(-) diff --git a/.zuul.yaml b/.zuul.yaml index 4e81e6f34..d5f278978 100644 --- a/.zuul.yaml +++ b/.zuul.yaml @@ -1,35 +1,13 @@ -- job: - name: openstacksdk-functional - parent: otc-tox-functional - description: | - Run openstacksdk functional tests against a OTC - -- job: - name: openstacksdk-functional-otc - parent: openstacksdk-functional - description: | - Run openstacksdk functional tests using default python against OTC - -- job: - name: openstacksdk-functional-otc-python3 - parent: openstacksdk-functional - description: | - Run openstacksdk functional tests using python3 against OTC - vars: - tox_environment: - OPENSTACKSDK_TOX_PYTHON: python3 - OS_CLOUD: otc - - project: check: jobs: - - tox-py36 - - tox-py27 + - tox-py37 - tox-pep8 - - openstacksdk-functional-otc-python3 + - tox-docs + - tox-functional gate: jobs: - - tox-py36 - - tox-py27 + - tox-py37 - tox-pep8 - - openstacksdk-functional-otc-python3 + - tox-functional + From 9d68b3352db9b9a916bc63f2c59ad160f8c610e0 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 20 Mar 2020 16:37:10 +0000 Subject: [PATCH 30/42] update .travis.yml --- .travis.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index ecd4b9dcf..0cfad8233 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,8 +3,6 @@ language: python cache: pip matrix: include: - - python: 2.7 - env: TOXENV=py27 - python: 3.6 env: TOXENV=py36 - python: 3.6 From 6d96fb7cacce70d98e0f299c7ac3de0012b14a10 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 20 Mar 2020 16:43:20 +0000 Subject: [PATCH 31/42] deleted coverage content and saved locally until content is available for pep8 --- doc/source/coverage.rst | 41 ++--------------------------------------- 1 file changed, 2 insertions(+), 39 deletions(-) diff --git a/doc/source/coverage.rst b/doc/source/coverage.rst index 3c3e6d821..867b882dd 100644 --- a/doc/source/coverage.rst +++ b/doc/source/coverage.rst @@ -6,42 +6,5 @@ to the vanilla OpenStack services implemented in OpenStack SDK. Two services (rds and cce) are currently covered in the documentation under several service tags. This may change in future. -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| ## | Service | Decription | CLI | GUI | PRX | RES | Comment | -+====+===============+==============================+=====+=====+=====+=====+=========+ -| 01 | anti_ddos | Anti-DDoS | X | . | X | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 02 | auto_scaling | Autoscaling | . | X | X | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 03 | cce | Cloud Container Engine | . | . | . | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 04 | cce_v1 | Cloud Container Engine | . | . | X | . | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 05 | cce_v2 | Cloud Container Engine | X | . | . | . | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 06 | cce_v3 | Cloud Container Engine | . | . | X | . | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 07 | cts | Cloud Trace Service | X | . | X | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 08 | dcs | Distributed Cache Service | X | . | X | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 09 | deh | Dedicated Host | X | X | X | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 10 | dms | Document Management Service | X | . | X | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 11 | dns | Domain Name Service | X | . | X | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 12 | kms | Key Management Service | X | . | X | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 13 | load_balancer | Load Balancer | X | . | . | . | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 14 | obs | Object Store | X | X | X | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 15 | rds | Relational Database Service | X | X | . | X | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 16 | rds_v1 | Relational Database Service | . | . | X | . | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 17 | rds_v3 | Relational Database Service | . | . | X | . | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ -| 18 | volume_backup | Volume Backup | X | X | X | . | | -+----+---------------+------------------------------+-----+-----+-----+-----+---------+ +.. note:: + Content is currently deleted until we found a better way to provide it. \ No newline at end of file From 4c1d489f0f6b4bf2acca4708cb3998d9f01b9674 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Fri, 20 Mar 2020 16:47:50 +0000 Subject: [PATCH 32/42] minor pep8 correction --- doc/source/coverage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/coverage.rst b/doc/source/coverage.rst index 867b882dd..f25103ef4 100644 --- a/doc/source/coverage.rst +++ b/doc/source/coverage.rst @@ -7,4 +7,4 @@ services (rds and cce) are currently covered in the documentation under several service tags. This may change in future. .. note:: - Content is currently deleted until we found a better way to provide it. \ No newline at end of file + Content is currently deleted until we found a better way to provide it. From 070b578e36f4767c1c76d4f747b233a80da09bfd Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Mon, 23 Mar 2020 15:25:59 +0000 Subject: [PATCH 33/42] Renew coverage.rst --- doc/source/coverage.rst | 109 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 2 deletions(-) diff --git a/doc/source/coverage.rst b/doc/source/coverage.rst index f25103ef4..75293748f 100644 --- a/doc/source/coverage.rst +++ b/doc/source/coverage.rst @@ -6,5 +6,110 @@ to the vanilla OpenStack services implemented in OpenStack SDK. Two services (rds and cce) are currently covered in the documentation under several service tags. This may change in future. -.. note:: - Content is currently deleted until we found a better way to provide it. +.. list-table:: + :name: service-coverage + :widths: 80 120 30 30 30 30 + :header-rows: 1 + + * - Endpoint + - Service + - GUI + - CLI + - SDK + - Comment + * - anti_ddos + - Anti-DDoS + - X + - X + - X + - + * - auto_scaling + - Auto-auto_scaling + - X + - X + - X + - + * - cce_v1 + - Cloud Container Engine + - X + - X + - X + - + * - cce_v3 + - Cloud Container Engine V2 + - X + - X + - X + - + * - cts + - Clout Trace Service + - X + - X + - X + - + * - dts + - Distributed Cache Service + - X + - X + - X + - + * - deh + - Dedicated Host + - X + - X + - X + - + * - dms + - Document Management Service + - X + - X + - X + - + * - dns + - Domain Name Service + - X + - X + - X + - + * - kms + - Key Management Service + - X + - X + - X + - + * - load_balancer + - Load Balancer + - X + - X + - + - + * - obs + - Object Storage Service + - X + - X + - X + - + * - rds + - Relational Database Service + - X + - X + - X + - + * - rds_v1 + - Relational Database Service + - + - + - + - + * - rds_v2 + - Relational Database Service + - + - + - + - + * - vbs + - Volume Backup + - X + - X + - X + - From 7ca8c0bf25f3cca6d044129be838fd6298e7ecaa Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Mon, 23 Mar 2020 15:30:02 +0000 Subject: [PATCH 34/42] added nat and ces to coverage.rst --- doc/source/coverage.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/doc/source/coverage.rst b/doc/source/coverage.rst index 75293748f..42805181b 100644 --- a/doc/source/coverage.rst +++ b/doc/source/coverage.rst @@ -8,7 +8,7 @@ under several service tags. This may change in future. .. list-table:: :name: service-coverage - :widths: 80 120 30 30 30 30 + :widths: 50 120 30 30 30 30 :header-rows: 1 * - Endpoint @@ -41,6 +41,12 @@ under several service tags. This may change in future. - X - X - + * - ces + - Cloudeye + - X + - + - + - * - cts - Clout Trace Service - X @@ -83,6 +89,12 @@ under several service tags. This may change in future. - X - - + * - nat + - Network Address Translation + - X + - + - + - * - obs - Object Storage Service - X From 2c30acd7e83f84a3c6697d8d97b596fed0cc357d Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Wed, 25 Mar 2020 14:57:17 +0000 Subject: [PATCH 35/42] CCE SDK guide added --- README.rst | 18 ++-- doc/source/sdk/guides/cce.rst | 145 ++++++++++++++++++++++++++++ doc/source/sdk/guides/index.rst | 1 + examples/cce/create_cluster.py | 53 ++++++++++ examples/cce/create_cluster_node.py | 53 ++++++++++ examples/cce/delete_cluster.py | 25 +++++ examples/cce/delete_cluster_node.py | 25 +++++ examples/cce/find_cluster.py | 24 +++++ examples/cce/find_cluster_node.py | 26 +++++ examples/cce/get_cluster.py | 24 +++++ examples/cce/get_cluster_node.py | 26 +++++ examples/cce/get_job.py | 24 +++++ examples/cce/list_cluster_nodes.py | 25 +++++ examples/cce/list_clusters.py | 22 +++++ examples/cce/wait_for_job.py | 25 +++++ 15 files changed, 509 insertions(+), 7 deletions(-) create mode 100644 doc/source/sdk/guides/cce.rst create mode 100644 examples/cce/create_cluster.py create mode 100644 examples/cce/create_cluster_node.py create mode 100644 examples/cce/delete_cluster.py create mode 100644 examples/cce/delete_cluster_node.py create mode 100644 examples/cce/find_cluster.py create mode 100644 examples/cce/find_cluster_node.py create mode 100644 examples/cce/get_cluster.py create mode 100644 examples/cce/get_cluster_node.py create mode 100644 examples/cce/get_job.py create mode 100644 examples/cce/list_cluster_nodes.py create mode 100644 examples/cce/list_clusters.py create mode 100644 examples/cce/wait_for_job.py diff --git a/README.rst b/README.rst index cc2d97920..018f6297e 100644 --- a/README.rst +++ b/README.rst @@ -18,6 +18,10 @@ the project interacts closely with the packages. +Documentation +------------- + +* `Documentation ` Installation ------------ @@ -28,10 +32,10 @@ and can be installed by pip as .. code-block: console $ pip install otcextensions -There are several options to do that including but not limited to pip -userland installation, system wide installation as well as -installation from operating system packets or directly from -source. Refer to the installation instructions_ in the projects +There are several options +to do that including but not limited to pip userland installation, system wide +installation as well as installation from operating system packets or directly +from source. Refer to the installation instructions_ in the projects documentation. @@ -56,6 +60,7 @@ authorization. For both there are several options available: clouds: otc: + profile: otc auth: username: "*username*" password: "*password*" @@ -129,11 +134,10 @@ Contributing See CONTRIBUTING.rst -Links -===== +Further Links +------------- * `Issue Tracker `_ -* `Documentation `_ .. _instructions: http://python-otcextensions.readthedocs.io/en/latest/install/ diff --git a/doc/source/sdk/guides/cce.rst b/doc/source/sdk/guides/cce.rst new file mode 100644 index 000000000..a5925356b --- /dev/null +++ b/doc/source/sdk/guides/cce.rst @@ -0,0 +1,145 @@ +Cloud Container Engine (CCE) +============================ + +.. contents:: Table of Contents + :local: + +CCE Cluster +----------- + +Cloud Container Engine (CCE) is a highly reliable and high-performance service +that allows enterprises to manage containerized applications. With support +for Kubernetes-native applications and tools, CCE makes it simple to set up +an environment for running containers in the cloud. CCE Clusters are the +environment where cluster nodes are administrated. The core component +is a Kubernetes Cluster with advanced features. + +List CCE Clusters +^^^^^^^^^^^^^^^^^ + +This interface is used to query all CCE clusters and to filter +the output with query parameters. + +.. literalinclude:: ../examples/cce/list_clusters.py + :lines: 16-22 + +Create CCE Cluster +^^^^^^^^^^^^^^^^^^ + +This interface is used to create a CCE cluster instance with +parameters. + +.. literalinclude:: ../examples/cce/create_cluster.py + :lines: 16-53 + +Get CCE Cluster +^^^^^^^^^^^^^^^ + +This interface is used to get a CCE cluster by ID +or an instance of class +:class:`~otcextensions.sdk.cce.v3.cluster.Cluster`. + +.. literalinclude:: ../examples/cce/get_cluster.py + :lines: 16-24 + +Find CCE Cluster +^^^^^^^^^^^^^^^^ + +This interface is used to find a CCE cluster by ID +or name. + +.. literalinclude:: ../examples/cce/find_cluster.py + :lines: 16-24 + +Delete CCE Cluster +^^^^^^^^^^^^^^^^^^ + +This interface is used to get a CCE cluster by ID +or an instance of class +:class:`~otcextensions.sdk.cce.v3.cluster.Cluster`. + +.. literalinclude:: ../examples/cce/delete_cluster.py + :lines: 16-25 + +CCE Node +-------- + +A CCE cluster node is the computing instance of a CCE cluster where +containers are hosted. One cluster can manage several nodes which +can be distributed over different availability zones to increase +reliability. + +List CCE Cluster Nodes +^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to query all nodes of a CCE cluster +and to filter the output with query parameters. + +.. literalinclude:: ../examples/cce/list_cluster_nodes.py + :lines: 16-25 + +Create CCE Cluster Node +^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to create a CCE cluster node instance with +parameters. + +.. literalinclude:: ../examples/cce/create_cluster_node.py + :lines: 16-53 + +Get CCE Cluster Node +^^^^^^^^^^^^^^^^^^^^ + +This interface is used to get a CCE cluster by ID +or an instance of class +:class:`~otcextensions.sdk.cce.v3.cluster_node.ClusterNode`. + +.. literalinclude:: ../examples/cce/get_cluster_node.py + :lines: 16-26 + +Find CCE Cluster Node +^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to find a node of a CCE cluster by ID +or name. + +.. literalinclude:: ../examples/cce/find_cluster_node.py + :lines: 16-26 + +Delete CCE Cluster Node +^^^^^^^^^^^^^^^^^^^^^^^ + +This interface is used to delete a CCE cluster node by ID +or an instance of class +:class:`~otcextensions.sdk.cce.v3.cluster_node.ClusterNode`. + +.. literalinclude:: ../examples/cce/delete_cluster_node.py + :lines: 16-25 + +Job Operations +-------------- + +Jobs are created while cluster creation and other similar operations +have been started. Jobs have different phases and can be triggered by +the following methods. + +Get Job +^^^^^^^ + +This interface is used to get a CCE Job by ID +or an instance of class +:class:`~otcextensions.sdk.cce.v3.job.Job`. + +.. literalinclude:: ../examples/cce/get_job.py + :lines: 16-24 + +Wait for a Job +^^^^^^^^^^^^^^ + +This interface is used to wait for a CCE Job until reaches a specific state +by using ID or an instance of class +:class:`~otcextensions.sdk.cce.v3.job.Job`. + +.. literalinclude:: ../examples/cce/wait_for_job.py + :lines: 16-24 + diff --git a/doc/source/sdk/guides/index.rst b/doc/source/sdk/guides/index.rst index 4229e6a27..75ecb8427 100644 --- a/doc/source/sdk/guides/index.rst +++ b/doc/source/sdk/guides/index.rst @@ -9,6 +9,7 @@ Open Telekom Cloud related User Guides anti_ddos auto_scaling + cce deh logging diff --git a/examples/cce/create_cluster.py b/examples/cce/create_cluster.py new file mode 100644 index 000000000..9ec082bcb --- /dev/null +++ b/examples/cce/create_cluster.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Create CCE Cluster +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +attrs = { + "kind": "Cluster", + "apiVersion": "v3", + "metadata": { + "name": "test2" + }, + "spec": { + "type": "VirtualMachine", + "flavor": "cce.s1.small", + "version": "v1.13.10-r0", + "az": "eu-de-01", + "supportIstio": True, + "hostNetwork": { + "vpc": "26ca2783-dc40-4e3a-95b1-5a0756441e12", + "subnet": "25d24fc8-d019-4a34-9fff-0a09fde6a9cb", + "SecurityGroup": "f9ae0767-25be-44fc-a21c-5b8a0da66dec" + }, + "containerNetwork": { + "mode": "overlay_l2", + "cidr": "172.16.0.0/16" + }, + "authentication": { + "mode": "rbac", + "authenticatingProxy": {} + }, + "billingMode": 0, + "kubernetesSvcIpRange": "10.247.0.0/16", + "kubeProxyMode": "iptables" + } +} + +conn.cce.create_cluster(**attrs) diff --git a/examples/cce/create_cluster_node.py b/examples/cce/create_cluster_node.py new file mode 100644 index 000000000..35068f946 --- /dev/null +++ b/examples/cce/create_cluster_node.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Create CCE Cluster node +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +attrs = { + "kind": "Cluster", + "apiVersion": "v3", + "metadata": { + "name": "test2" + }, + "spec": { + "type": "VirtualMachine", + "flavor": "cce.s1.small", + "version": "v1.13.10-r0", + "az": "eu-de-01", + "supportIstio": True, + "hostNetwork": { + "vpc": "26ca2783-dc40-4e3a-95b1-5a0756441e12", + "subnet": "25d24fc8-d019-4a34-9fff-0a09fde6a9cb", + "SecurityGroup": "f9ae0767-25be-44fc-a21c-5b8a0da66dec" + }, + "containerNetwork": { + "mode": "overlay_l2", + "cidr": "172.16.0.0/16" + }, + "authentication": { + "mode": "rbac", + "authenticatingProxy": {} + }, + "billingMode": 0, + "kubernetesSvcIpRange": "10.247.0.0/16", + "kubeProxyMode": "iptables" + } +} + +conn.cce.create_cluster_node(**attrs) diff --git a/examples/cce/delete_cluster.py b/examples/cce/delete_cluster.py new file mode 100644 index 000000000..9aff2c8fb --- /dev/null +++ b/examples/cce/delete_cluster.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get a CCE cluster by id or class Cluster +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +cluster_name = "cluster_name" +cluster = conn.cce.find_cluster(cluster_name) +print(cluster) +conn.cce.delete_cluster(cluster) diff --git a/examples/cce/delete_cluster_node.py b/examples/cce/delete_cluster_node.py new file mode 100644 index 000000000..7673875e6 --- /dev/null +++ b/examples/cce/delete_cluster_node.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Delete a CCE cluster node +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +cluster = "cluster_name_or_id" +cluster = conn.cce.find_cluster(cluster) +node_id = "node_id" +conn.cce.delete_cluster_node(cluster, node_id) diff --git a/examples/cce/find_cluster.py b/examples/cce/find_cluster.py new file mode 100644 index 000000000..ec1a796bf --- /dev/null +++ b/examples/cce/find_cluster.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get a CCE cluster by id or class Cluster +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +cluster = "cluster_name_or_id" +cluster = conn.cce.find_cluster(cluster) +print(cluster) diff --git a/examples/cce/find_cluster_node.py b/examples/cce/find_cluster_node.py new file mode 100644 index 000000000..c1dfd17f3 --- /dev/null +++ b/examples/cce/find_cluster_node.py @@ -0,0 +1,26 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Find a CCE cluster node by name or id +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +cluster = "cluster_name_or_id" +cluster = conn.cce.find_cluster(cluster) +node = "node_name_or_id" +node = conn.cce.find_cluster_node(cluster, node) +print(node) diff --git a/examples/cce/get_cluster.py b/examples/cce/get_cluster.py new file mode 100644 index 000000000..0263c2011 --- /dev/null +++ b/examples/cce/get_cluster.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get a CCE cluster by id or class Cluster +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +cluster_id = "123456_cluster_id" +cluster = conn.cce.get_cluster(cluster_id) +print(cluster) diff --git a/examples/cce/get_cluster_node.py b/examples/cce/get_cluster_node.py new file mode 100644 index 000000000..448c49084 --- /dev/null +++ b/examples/cce/get_cluster_node.py @@ -0,0 +1,26 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get a CCE cluster node by id or class ClusterNode +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +cluster = "cluster_name_or_id" +cluster = conn.cce.find_cluster(cluster) +node_id = "node_id" +node = conn.cce.get_cluster_node(cluster, node_id) +print(node) diff --git a/examples/cce/get_job.py b/examples/cce/get_job.py new file mode 100644 index 000000000..0a3fec904 --- /dev/null +++ b/examples/cce/get_job.py @@ -0,0 +1,24 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Get a Job by id or instance of class Job +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +job_id = "123456_job_id" +job = conn.cce.get_job(job_id) +print(job) diff --git a/examples/cce/list_cluster_nodes.py b/examples/cce/list_cluster_nodes.py new file mode 100644 index 000000000..cf0016ac6 --- /dev/null +++ b/examples/cce/list_cluster_nodes.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List all nodes of a CCE cluster +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +cluster = "cluster_name_or_id" +cluster = conn.cce.find_cluster(cluster) +for node in conn.cce.cluster_nodes(cluster): + print(node) diff --git a/examples/cce/list_clusters.py b/examples/cce/list_clusters.py new file mode 100644 index 000000000..da61925d7 --- /dev/null +++ b/examples/cce/list_clusters.py @@ -0,0 +1,22 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +List all CCE clusters +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + +for cluster in conn.cce.clusters(): + print(cluster) diff --git a/examples/cce/wait_for_job.py b/examples/cce/wait_for_job.py new file mode 100644 index 000000000..03c033503 --- /dev/null +++ b/examples/cce/wait_for_job.py @@ -0,0 +1,25 @@ +#!/usr/bin/env python3 +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +""" +Wait for a job until it reaches a specific status +""" +import openstack + +openstack.enable_logging(True) +conn = openstack.connect(cloud='otc') + + +job_id = "123456_job_id" +conn.cce.wait_for_job(job_id, status='success', + failures=None, interval=5, wait=3600) +print('Done') From d9c7ff8c70157bb03e6d240ada0e2ee866c4a521 Mon Sep 17 00:00:00 2001 From: Artem Goncharov Date: Thu, 6 Feb 2020 15:58:47 +0100 Subject: [PATCH 36/42] Update .zuul.yaml --- .zuul.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.zuul.yaml b/.zuul.yaml index d5f278978..cef56795b 100644 --- a/.zuul.yaml +++ b/.zuul.yaml @@ -10,4 +10,3 @@ - tox-py37 - tox-pep8 - tox-functional - From fef79865ff3732b829a787cdefbf0216f7f3095e Mon Sep 17 00:00:00 2001 From: Artem Goncharov Date: Thu, 6 Feb 2020 18:12:21 +0100 Subject: [PATCH 37/42] Create bindep.txt --- bindep.txt | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 bindep.txt diff --git a/bindep.txt b/bindep.txt new file mode 100644 index 000000000..eb458b065 --- /dev/null +++ b/bindep.txt @@ -0,0 +1,6 @@ +build-essential [platform:dpkg] +python-dev [platform:dpkg] +python-devel [platform:rpm] +libffi-dev [platform:dpkg] +libffi-devel [platform:rpm] +openssl-devel [platform:rpm] From f3f0baf57701808eaa4401999c58df6087bccacb Mon Sep 17 00:00:00 2001 From: Artem Goncharov Date: Tue, 11 Feb 2020 20:21:35 +0100 Subject: [PATCH 38/42] some dns private zone fixes --- otcextensions/osclient/dns/v2/recordset.py | 37 +++++++++++++++++++--- otcextensions/sdk/dns/v2/_proxy.py | 5 +-- 2 files changed, 36 insertions(+), 6 deletions(-) diff --git a/otcextensions/osclient/dns/v2/recordset.py b/otcextensions/osclient/dns/v2/recordset.py index 581315365..3ee414c91 100644 --- a/otcextensions/osclient/dns/v2/recordset.py +++ b/otcextensions/osclient/dns/v2/recordset.py @@ -50,16 +50,24 @@ def get_parser(self, prog_name): help=_('UUID or name of the zone. Recordsets of all zones ' 'will be returned if not given.') ) + parser.add_argument( + '--zone-type', + help=_('DNS Zone type (private/public)') + ) return parser def take_action(self, parsed_args): client = self.app.client_manager.dns zone = None + attrs = {} + if parsed_args.zone_type: + attrs['zone_type'] = parsed_args.zone_type if parsed_args.zone: - zone = client.find_zone(parsed_args.zone, ignore_missing=False) + zone = client.find_zone(parsed_args.zone, ignore_missing=False, + **attrs) data = client.recordsets(zone=zone) @@ -81,6 +89,10 @@ def get_parser(self, prog_name): metavar='', help=_('UUID or name of the zone.') ) + parser.add_argument( + '--zone-type', + help=_('DNS Zone type (private/public)') + ) parser.add_argument( 'recordset', @@ -96,6 +108,8 @@ def take_action(self, parsed_args): zone = client.find_zone( parsed_args.zone, + ignore_missing=False, + zone_type=parsed_args.zone_type ) obj = client.find_recordset(zone=zone, @@ -118,6 +132,10 @@ def get_parser(self, prog_name): metavar='', help=_('UUID or name of the zone.') ) + parser.add_argument( + '--zone-type', + help=_('DNS Zone type (private/public)') + ) parser.add_argument( 'recordset', @@ -131,7 +149,8 @@ def get_parser(self, prog_name): def take_action(self, parsed_args): if parsed_args.zone: client = self.app.client_manager.dns - zone = client.find_zone(parsed_args.zone, ignore_missing=False) + zone = client.find_zone(parsed_args.zone, ignore_missing=False, + zone_type=parsed_args.zone_type) for rs in parsed_args.recordset: rs = client.find_recordset(zone=zone, name_or_id=rs, ignore_missing=False) @@ -150,6 +169,10 @@ def get_parser(self, prog_name): metavar='', help=_('UUID or name of the zone.') ) + parser.add_argument( + '--zone-type', + help=_('DNS Zone type (private/public)') + ) parser.add_argument( '--name', metavar='', @@ -193,7 +216,8 @@ def take_action(self, parsed_args): attrs = {'records': []} - zone = client.find_zone(parsed_args.zone, ignore_missing=False) + zone = client.find_zone(parsed_args.zone, ignore_missing=False, + zone_type=parsed_args.zone_type) if parsed_args.name: attrs['name'] = parsed_args.name @@ -228,6 +252,10 @@ def get_parser(self, prog_name): metavar='', help=_('UUID or name of the zone.') ) + parser.add_argument( + '--zone-type', + help=_('DNS Zone type (private/public)') + ) parser.add_argument( 'recordset', metavar='', @@ -268,7 +296,8 @@ def take_action(self, parsed_args): if parsed_args.ttl: attrs['ttl'] = parsed_args.ttl - zone = client.find_zone(parsed_args.zone, ignore_missing=False) + zone = client.find_zone(parsed_args.zone, ignore_missing=False, + zone_type=parsed_args.zone_type) if parsed_args.ttl: attrs['zone_id'] = zone.id diff --git a/otcextensions/sdk/dns/v2/_proxy.py b/otcextensions/sdk/dns/v2/_proxy.py index 481a80b03..6d7c0b3ac 100644 --- a/otcextensions/sdk/dns/v2/_proxy.py +++ b/otcextensions/sdk/dns/v2/_proxy.py @@ -83,7 +83,7 @@ def update_zone(self, zone, **attrs): """ return self._update(_zone.Zone, zone, **attrs) - def find_zone(self, name_or_id, ignore_missing=True): + def find_zone(self, name_or_id, ignore_missing=True, **attrs): """Find a single zone :param name_or_id: The name or ID of a zone @@ -96,7 +96,8 @@ def find_zone(self, name_or_id, ignore_missing=True): :returns: ``None`` """ return self._find(_zone.Zone, name_or_id, - ignore_missing=ignore_missing) + ignore_missing=ignore_missing, + **attrs) def add_router_to_zone(self, zone, **router): """Add router(VPC) to private zone From b04e8f72e9747c616f145ed23699eae4b74e0bbc Mon Sep 17 00:00:00 2001 From: Artem Goncharov Date: Fri, 14 Feb 2020 15:42:48 +0100 Subject: [PATCH 39/42] Zuul (#63) * reset zuul integration * disable tox-docs for separate branch * replace openstacksdk general error handler * exclude rds instance osc func tests * blacklist failing tests * repair func test cmd * compare if we got something * fix pep --- .stestr.blacklist.functional | 8 ++++++++ otcextensions/common/exc.py | 2 ++ otcextensions/sdk/__init__.py | 3 +++ .../tests/functional/osclient/rds/v3/test_flavor.py | 9 +++++---- tox.ini | 2 +- 5 files changed, 19 insertions(+), 5 deletions(-) create mode 100644 .stestr.blacklist.functional diff --git a/.stestr.blacklist.functional b/.stestr.blacklist.functional new file mode 100644 index 000000000..aa3c7a5ed --- /dev/null +++ b/.stestr.blacklist.functional @@ -0,0 +1,8 @@ +otcextensions.tests.functional.osclient.obs* +otcextensions.tests.functional.osclient.rds.v3.test_instance* +otcextensions.tests.functional.osclient.volume_backup* +otcextensions.tests.functional.sdk.cce.v1* +otcextensions.tests.functional.sdk.kms* +otcextensions.tests.functional.sdk.volume_backup* +otcextensions.tests.functional.sdk.volume_backup* +otcextensions.tests.functional.sdk.deh* diff --git a/otcextensions/common/exc.py b/otcextensions/common/exc.py index 897972be5..061ba1c47 100644 --- a/otcextensions/common/exc.py +++ b/otcextensions/common/exc.py @@ -236,6 +236,8 @@ def raise_from_response(response, error_message=None): messages = [content['message'], ] if 'error_code' in content: details = content['error_code'] + if 'error_msg' in content: + messages = [content['error_msg'], ] else: messages = [obj.get('message') for obj in content.values() if isinstance(obj, dict)] diff --git a/otcextensions/sdk/__init__.py b/otcextensions/sdk/__init__.py index 41cf95de1..8de28244e 100644 --- a/otcextensions/sdk/__init__.py +++ b/otcextensions/sdk/__init__.py @@ -17,6 +17,7 @@ from openstack import utils from otcextensions.sdk.compute.v2 import server +from otcextensions.common import exc _logger = _log.setup_logging('openstack') @@ -209,6 +210,8 @@ def patch_openstack_resources(): server.Server._get_tag_struct openstack.compute.v2.server.Server.add_tag = server.Server.add_tag openstack.compute.v2.server.Server.remove_tag = server.Server.remove_tag + openstack.exceptions.raise_from_response = \ + exc.raise_from_response def load(conn, **kwargs): diff --git a/otcextensions/tests/functional/osclient/rds/v3/test_flavor.py b/otcextensions/tests/functional/osclient/rds/v3/test_flavor.py index ab9a830e9..7400921ce 100644 --- a/otcextensions/tests/functional/osclient/rds/v3/test_flavor.py +++ b/otcextensions/tests/functional/osclient/rds/v3/test_flavor.py @@ -41,10 +41,11 @@ def test_flavor_list(self): )) self.assertIsNotNone(json_output) - self.assertEqual( - ['name', 'instance_mode', 'vcpus', 'ram'], - list(json_output[0].keys()) - ) + if len(json_output) > 0: + self.assertEqual( + ['name', 'instance_mode', 'vcpus', 'ram'], + list(json_output[0].keys()) + ) def test_invalid_datastore_flavor_list(self): self.assertRaises( diff --git a/tox.ini b/tox.ini index 02190deca..4a5cafd7f 100644 --- a/tox.ini +++ b/tox.ini @@ -32,7 +32,7 @@ commands = stestr --test-path ./otcextensions/tests/examples run {posargs} setenv = {[testenv]setenv} OS_TEST_TIMEOUT=60 -commands = stestr --test-path ./otcextensions/tests/functional run --serial {posargs} +commands = stestr --test-path ./otcextensions/tests/functional run --serial --blacklist-file .stestr.blacklist.functional {posargs} stestr slowest [testenv:pep8] From 3a701042c2abe26496927ff52d8c2e20c21695a3 Mon Sep 17 00:00:00 2001 From: "T. Schreiber" Date: Mon, 24 Feb 2020 11:37:44 +0100 Subject: [PATCH 40/42] AS corrections for new API Version (#60) * improve Auto_Scaling user experience by using openstack client * flake8 corrections * change group unit test for AS service * bug fixing * fix policy * add policy delete * minor fixes * ensure --group on policy update * pep 8 corrections and unit test fixes * change CLI client parameters from using underscore to dash * Update test_policy.py * Renaming of network parameters and fixing unit tests --- .../osclient/auto_scaling/v1/activity.py | 7 +- .../osclient/auto_scaling/v1/config.py | 8 +- .../osclient/auto_scaling/v1/group.py | 144 +++++++++++------- .../osclient/auto_scaling/v1/instance.py | 14 +- .../osclient/auto_scaling/v1/policy.py | 82 +++++----- otcextensions/sdk/auto_scaling/v1/_base.py | 12 ++ otcextensions/sdk/auto_scaling/v1/_proxy.py | 7 +- otcextensions/sdk/auto_scaling/v1/config.py | 2 +- otcextensions/sdk/auto_scaling/v1/group.py | 16 +- otcextensions/sdk/auto_scaling/v1/policy.py | 75 ++++++++- .../unit/osclient/auto_scaling/v1/fakes.py | 2 +- .../osclient/auto_scaling/v1/test_activity.py | 6 +- .../osclient/auto_scaling/v1/test_config.py | 2 +- .../osclient/auto_scaling/v1/test_group.py | 113 ++++++++------ .../osclient/auto_scaling/v1/test_instance.py | 22 +-- .../osclient/auto_scaling/v1/test_policy.py | 42 ++--- .../unit/sdk/auto_scaling/v1/test_group.py | 2 +- .../unit/sdk/auto_scaling/v1/test_policy.py | 2 - .../unit/sdk/auto_scaling/v1/test_proxy.py | 8 +- setup.cfg | 1 + 20 files changed, 360 insertions(+), 207 deletions(-) diff --git a/otcextensions/osclient/auto_scaling/v1/activity.py b/otcextensions/osclient/auto_scaling/v1/activity.py index ea6d014db..bf44dc171 100644 --- a/otcextensions/osclient/auto_scaling/v1/activity.py +++ b/otcextensions/osclient/auto_scaling/v1/activity.py @@ -31,18 +31,19 @@ class ListAutoScalingActivityLogs(command.Lister): def get_parser(self, prog_name): parser = super(ListAutoScalingActivityLogs, self).get_parser(prog_name) parser.add_argument( - 'group', + '--group', metavar='', + required=True, help=_('AS Group ID or name') ) parser.add_argument( - '--start_time', + '--start-time', metavar='', help=_('Specifies the start time for querying scaling ' 'action logs. Format: `YYYY-MM-DDThh:mm:ssZ`') ) parser.add_argument( - '--end_time', + '--end-time', metavar='', help=_('Specifies the end time for querying scaling ' 'action logs. Format: `YYYY-MM-DDThh:mm:ssZ`') diff --git a/otcextensions/osclient/auto_scaling/v1/config.py b/otcextensions/osclient/auto_scaling/v1/config.py index d29bf03c3..f839cf89e 100644 --- a/otcextensions/osclient/auto_scaling/v1/config.py +++ b/otcextensions/osclient/auto_scaling/v1/config.py @@ -152,13 +152,13 @@ def get_parser(self, prog_name): help=_('Flavor ID or Name for the ECS instance') ) group1.add_argument( - '--image_id', + '--image-id', metavar='', help=_('Image ID for the ECS instance to be created') ) group = parser.add_mutually_exclusive_group() group.add_argument( - '--instance_id', + '--instance-id', metavar='', help=_('AS Configuration name\n' 'Is mutually exclusive with ECS group') @@ -187,14 +187,14 @@ def get_parser(self, prog_name): help=_('Key name for the new ECS instance') ) parser.add_argument( - '--public_ip_bandwith', + '--public-ip-bandwith', metavar='', type=int, help=_('Defines EIP Bandwith (Mbit/s) to be attached ' 'to the new ECS instance') ) parser.add_argument( - '--user_data', + '--user-data', metavar='', help=_('Path to the cloud-init user_data file') ) diff --git a/otcextensions/osclient/auto_scaling/v1/group.py b/otcextensions/osclient/auto_scaling/v1/group.py index cded083a7..0fac7b320 100644 --- a/otcextensions/osclient/auto_scaling/v1/group.py +++ b/otcextensions/osclient/auto_scaling/v1/group.py @@ -62,6 +62,11 @@ class ListAutoScalingGroup(command.Lister): def get_parser(self, prog_name): parser = super(ListAutoScalingGroup, self).get_parser(prog_name) + parser.add_argument( + '--name', + metavar='', + help=_('Name or ID of the AS group') + ) parser.add_argument( '--limit', dest='limit', @@ -78,13 +83,40 @@ def get_parser(self, prog_name): 'specified marker. When used with --limit, set this to ' 'the last ID displayed in the previous run') ) + parser.add_argument( + '--scaling-configuration-id', + metavar='', + help=_('ID of the AS configuration') + ) + parser.add_argument( + '--status', + metavar='', + help=_('Shows AS groups with specific status:\n' + ': AS group is working\n' + ': AS group is paused\n' + ': AS group has malfunctions\n' + ': AS group is being deleted') + ) return parser def take_action(self, parsed_args): client = self.app.client_manager.auto_scaling - data = client.groups() + args = {} + if parsed_args.limit: + args['limit'] = parsed_args.limit + if parsed_args.marker: + args['marker'] = parsed_args.marker + if parsed_args.name: + args['name'] = parsed_args.name + if parsed_args.scaling_configuration_id: + args['scaling_configuration_id'] = \ + parsed_args.scaling_configuration_id + if parsed_args.status: + args['status'] = parsed_args.status + + data = client.groups(**args) return ( self.columns, @@ -137,36 +169,36 @@ def get_parser(self, prog_name): help=_('Name of the new configuration group') ) parser.add_argument( - '--desire_instance_number', + '--desire-instance-number', metavar='', type=int, help=_('Desired number of instances') ) parser.add_argument( - '--min_instance_number', + '--min-instance-number', metavar='', type=int, help=_('Minimal number of instances') ) parser.add_argument( - '--max_instance_number', + '--max-instance-number', metavar='', type=int, help=_('Maximal number of instances') ) parser.add_argument( - '--cool_down_time', + '--cool-down-time', metavar='', type=int, help=_('Specifies cooling duration in seconds') ) parser.add_argument( - '--lb_listener_id', + '--lb-listener-id', metavar='', help=_('Specifies ELB Listener ID') ) parser.add_argument( - '--lbaas_listener', + '--lbaas-listener', metavar='', action='append', help=_('Specifies ULB Listener Information in format: ' @@ -174,47 +206,47 @@ def get_parser(self, prog_name): '(Repeat multiple times, up to 3 times)') ) parser.add_argument( - '--availability_zone', + '--availability-zone', metavar='', action='append', help=_('Specifies the availability zones information ' '(Repeat multiple times)') ) parser.add_argument( - '--subnet', - metavar='', + '--network-id', + metavar='', action='append', required=True, help=_('Network ID of the subnet' '(Repeat multiple times, up to 5 times)') ) parser.add_argument( - '--security_group', + '--security-group', metavar='', action='append', - required=True, + # required=True, help=_('Security Group ID' '(Repeat multiple times)') ) parser.add_argument( - '--router', - metavar='', + '--router-id', + metavar='', required=True, help=_('Router (VPC) ID') ) parser.add_argument( - '--audit_method', + '--audit-method', metavar='', help=_('Specifies the audit method [`NOVA_AUDIT`, `ELB_AUDIT`]') ) parser.add_argument( - '--audit_time', + '--audit-time', metavar='', type=int, help=_('Specifies the audit time in minutes') ) parser.add_argument( - '--terminate_policy', + '--terminate-policy', metavar='', help=_('Specifies the termination policy' ' [`OLD_CONFIG_OLD_INSTANCE` (default), ' @@ -230,7 +262,7 @@ def get_parser(self, prog_name): '(Repeat multiple times)') ) parser.add_argument( - '--delete_public_ip', + '--delete-public-ip', default=False, action='store_true', help=_('Specifies whether to delete EIP when deleting the ECS') @@ -241,17 +273,18 @@ def take_action(self, parsed_args): args = {} args['name'] = parsed_args.name - args['vpc_id'] = parsed_args.router + args['router_id'] = parsed_args.router_id - subnets = [] - for subnet in parsed_args.subnet: - subnets.append({'id': subnet}) - args['networks'] = subnets + networks = [] + for network in parsed_args.network_id: + networks.append({'id': network}) + args['networks'] = networks - sgs = [] - for sg in parsed_args.security_group: - sgs.append({'id': sg}) - args['security_groups'] = sgs + if parsed_args.security_group: + sgs = [] + for sg in parsed_args.security_group: + sgs.append({'id': sg}) + args['security_groups'] = sgs if parsed_args.desire_instance_number: args['desire_instance_number'] = parsed_args.desire_instance_number @@ -337,36 +370,36 @@ def get_parser(self, prog_name): help=_('AS Group name or ID') ) parser.add_argument( - '--desire_instance_number', + '--desire-instance-number', metavar='', type=int, help=_('Desired number of instances') ) parser.add_argument( - '--min_instance_number', + '--min-instance-number', metavar='', type=int, help=_('Minimal number of instances') ) parser.add_argument( - '--max_instance_number', + '--max-instance-number', metavar='', type=int, help=_('Maximal number of instances') ) parser.add_argument( - '--cool_down_time', + '--cool-down-time', metavar='', type=int, help=_('Specifies cooling duration in seconds') ) parser.add_argument( - '--lb_listener_id', + '--lb-listener-id', metavar='', help=_('Specifies ELB Listener ID') ) parser.add_argument( - '--lbaas_listener', + '--lbaas-listener', metavar='', action='append', help=_('Specifies ULB Listener Information in format: ' @@ -374,47 +407,46 @@ def get_parser(self, prog_name): '(Repeat multiple times, up to 3 times)') ) parser.add_argument( - '--availability_zone', + '--availability-zone', metavar='', action='append', help=_('Specifies the availability zones information ' '(Repeat multiple times)') ) parser.add_argument( - '--subnetwork', - metavar='', + '--network-id', + metavar='', + default=[], action='append', - required=True, help=_('Network ID of the subnet' '(Repeat multiple times, up to 5 times)') ) parser.add_argument( - '--security_group', + '--security-group', metavar='', + default=[], action='append', - required=True, help=_('Security Group ID' '(Repeat multiple times)') ) parser.add_argument( - '--network_id', - metavar='', - required=True, - help=_('Network (VPC) ID') + '--router-id', + metavar='', + help=_('Router (VPC) ID') ) parser.add_argument( - '--audit_method', + '--audit-method', metavar='', help=_('Specifies the audit method [`NOVA_AUDIT`, `ELB_AUDIT`]') ) parser.add_argument( - '--audit_time', + '--audit-time', metavar='', type=int, help=_('Specifies the audit time in minutes') ) parser.add_argument( - '--terminate_policy', + '--terminate-policy', metavar='', help=_('Specifies the termination policy' ' [`OLD_CONFIG_OLD_INSTANCE` (default), ' @@ -430,7 +462,7 @@ def get_parser(self, prog_name): '(Repeat multiple times)') ) parser.add_argument( - '--delete_public_ip', + '--delete-public-ip', default=False, action='store_true', help=_('Specifies whether to delete EIP when deleting the ECS') @@ -440,17 +472,20 @@ def get_parser(self, prog_name): def take_action(self, parsed_args): args = {} - args['vpc_id'] = parsed_args.network_id + if parsed_args.router_id: + args['router_id'] = parsed_args.router_id - subnets = [] - for subnet in parsed_args.subnetwork: - subnets.append({'id': subnet}) - args['networks'] = subnets + networks = [] + for network in parsed_args.network_id: + networks.append({'id': network}) + if networks: + args['networks'] = networks sgs = [] for sg in parsed_args.security_group: sgs.append({'id': sg}) - args['security_groups'] = sgs + if sgs: + args['security_groups'] = sgs if parsed_args.desire_instance_number: args['desire_instance_number'] = parsed_args.desire_instance_number @@ -495,7 +530,8 @@ def take_action(self, parsed_args): args['notifications'] = lst client = self.app.client_manager.auto_scaling - group = client.update_group(group=parsed_args.group, **args) + group = client.find_group(parsed_args.group, ignore_missing=False) + group = client.update_group(group, **args) display_columns, columns = _get_columns(group) data = utils.get_item_properties(group, columns, formatters={}) diff --git a/otcextensions/osclient/auto_scaling/v1/instance.py b/otcextensions/osclient/auto_scaling/v1/instance.py index 061c09b78..03f55608d 100644 --- a/otcextensions/osclient/auto_scaling/v1/instance.py +++ b/otcextensions/osclient/auto_scaling/v1/instance.py @@ -31,18 +31,19 @@ class ListAutoScalingInstance(command.Lister): def get_parser(self, prog_name): parser = super(ListAutoScalingInstance, self).get_parser(prog_name) parser.add_argument( - 'group', + '--group', metavar='', + required=True, help=_('AS Group ID or Name for the instances query') ) parser.add_argument( - '--life_cycle_state', + '--life-cycle-state', metavar='', help=_('Life cycle state of the instances to query\n' 'Could be in [`INSERVICE`, `PENDING`, `REMOVING`]') ) parser.add_argument( - '--health_status', + '--health-status', metavar='', help=_('Health status of the instances to query\n' 'Could be in [`INITIALIZING`, `NORMAL`, `ERROR`]') @@ -91,7 +92,7 @@ def get_parser(self, prog_name): help=_('AS Instance ID to be deleted') ) parser.add_argument( - '--delete_instance', + '--delete-instance', action='store_true', default=False, help=_('Specifies, whether instance should be completely deleted') @@ -117,8 +118,9 @@ def get_parser(self, prog_name): parser = super(BatchActionAutoScalingInstance, self).\ get_parser(prog_name) parser.add_argument( - 'group', + '--group', metavar='', + required=True, help=_('AS Group ID or Name') ) parser.add_argument( @@ -134,7 +136,7 @@ def get_parser(self, prog_name): help=_('AS Instance ID to be deleted') ) parser.add_argument( - '--delete_instance', + '--delete-instance', action='store_true', default=False, help=_('Specifies, whether instance should be completely deleted' diff --git a/otcextensions/osclient/auto_scaling/v1/policy.py b/otcextensions/osclient/auto_scaling/v1/policy.py index e17755052..f0baacbea 100644 --- a/otcextensions/osclient/auto_scaling/v1/policy.py +++ b/otcextensions/osclient/auto_scaling/v1/policy.py @@ -104,18 +104,26 @@ def get_parser(self, prog_name): parser.add_argument( 'policy', metavar='', - help=_('ID of the configuration policy') + help=_('ID of the configuration policy\n' + 'For Policy Name search --group param is needed') + ) + parser.add_argument( + '--group', + metavar='', + help=_('ScalingGroup ID or Name if Name searched is used') ) return parser def take_action(self, parsed_args): client = self.app.client_manager.auto_scaling - obj = client.get_policy(parsed_args.policy) - - # display_columns, columns = _get_columns(obj) - # data = utils.get_item_properties( - # obj, columns, formatters={'instance_config': _format_instance}) + if parsed_args.group: + group = client.find_group(parsed_args.group, ignore_missing=False) + obj = client.find_policy(parsed_args.policy, + group=group, + ignore_missing=False) + else: + obj = client.get_policy(parsed_args.policy) fmt = set_attributes_for_print_detail(obj) # display_columns, columns = _get_columns(obj) @@ -159,30 +167,30 @@ def get_parser(self, prog_name): help=_('AS Policy type [`ALARM`, `SCHEDULED`, `RECURRENCE`]') ) parser.add_argument( - '--cool_down_time', + '--cool-down-time', metavar='', type=int, help=_('Specifies the cooling time in seconds for the policy') ) parser.add_argument( - '--alarm_id', + '--alarm-id', metavar='', help=_('Specifies the alarm_id for the policy') ) parser.add_argument( - '--action_operation', + '--action-operation', metavar='', help=_('Specifies the policy operation ' 'Can be [`ADD`, `REMOVE`, `SET`]') ) parser.add_argument( - '--action_instance_number', + '--action-instance-number', metavar='', type=int, help=_('Specifies number of instances to be operated') ) parser.add_argument( - '--launch_time', + '--launch-time', metavar='', help=_('Specifies the time when the scaling action is triggered. ' 'The time format must comply with UTC.\n' @@ -190,7 +198,7 @@ def get_parser(self, prog_name): '* when type=`RECURRENCE`, then `hh:mm`\n') ) parser.add_argument( - '--recurrence_type', + '--recurrence-type', metavar='', help=_( 'Specifies the periodic triggering type\n' @@ -199,7 +207,7 @@ def get_parser(self, prog_name): ) ) parser.add_argument( - '--recurrence_value', + '--recurrence-value', metavar='', help=_( 'Specifies the frequency, at which actions are triggered\n' @@ -210,13 +218,13 @@ def get_parser(self, prog_name): ) ) parser.add_argument( - '--start_time', + '--start-time', metavar='', help=_('Specifies the start time in of the action in the ' '`YYYY-MM-DDThh:mmZ` format') ) parser.add_argument( - '--end_time', + '--end-time', metavar='', help=_('Specifies the end time in of the action in the ' '`YYYY-MM-DDThh:mmZ` format\n' @@ -315,7 +323,7 @@ def get_parser(self, prog_name): parser.add_argument( 'policy', metavar='', - help=_('AS Policy name or ID') + help=_('AS Policy ID') ) parser.add_argument( '--group', @@ -326,35 +334,33 @@ def get_parser(self, prog_name): parser.add_argument( '--type', metavar='', - required=True, - # choices=['ALARM', 'SCHEDULED', 'RECURRENCE'], help=_('AS Policy type [`ALARM`, `SCHEDULED`, `RECURRENCE`]') ) parser.add_argument( - '--cool_down_time', + '--cool-down-time', metavar='', type=int, help=_('Specifies the cooling time in seconds for the policy') ) parser.add_argument( - '--alarm_id', + '--alarm-id', metavar='', help=_('Specifies the alarm_id for the policy') ) parser.add_argument( - '--action_operation', + '--action-operation', metavar='', help=_('Specifies the policy operation ' 'Can be [`ADD`, `REMOVE`, `SET`]') ) parser.add_argument( - '--action_instance_number', + '--action-instance-number', metavar='', type=int, help=_('Specifies number of instances to be operated') ) parser.add_argument( - '--launch_time', + '--launch-time', metavar='', help=_('Specifies the time when the scaling action is triggered. ' 'The time format must comply with UTC.\n' @@ -362,7 +368,7 @@ def get_parser(self, prog_name): '* when type=`RECURRENCE`, then `hh:mm`\n') ) parser.add_argument( - '--recurrence_type', + '--recurrence-type', metavar='', help=_( 'Specifies the periodic triggering type\n' @@ -371,7 +377,7 @@ def get_parser(self, prog_name): ) ) parser.add_argument( - '--recurrence_value', + '--recurrence-value', metavar='', help=_( 'Specifies the frequency, at which actions are triggered\n' @@ -382,13 +388,13 @@ def get_parser(self, prog_name): ) ) parser.add_argument( - '--start_time', + '--start-time', metavar='', help=_('Specifies the start time in of the action in the ' '`YYYY-MM-DDThh:mmZ` format') ) parser.add_argument( - '--end_time', + '--end-time', metavar='', help=_('Specifies the end time in of the action in the ' '`YYYY-MM-DDThh:mmZ` format\n' @@ -401,13 +407,14 @@ def take_action(self, parsed_args): policy_attrs = {} # policy_attrs['name'] = parsed_args.name policy_attrs['scaling_group_id'] = parsed_args.group - policy_type = parsed_args.type.upper() - if policy_type not in self.POLICY_TYPES: - msg = (_('Unsupported policy type. Should be one of %s') - % self.POLICY_TYPES) - raise argparse.ArgumentTypeError(msg) - else: - policy_attrs['type'] = policy_type + if parsed_args.type: + policy_type = parsed_args.type.upper() + if policy_type not in self.POLICY_TYPES: + msg = (_('Unsupported policy type. Should be one of %s') + % self.POLICY_TYPES) + raise argparse.ArgumentTypeError(msg) + else: + policy_attrs['type'] = policy_type if parsed_args.alarm_id: policy_attrs['alarm_id'] = parsed_args.alarm_id if parsed_args.cool_down_time: @@ -437,8 +444,9 @@ def take_action(self, parsed_args): client = self.app.client_manager.auto_scaling + policy = client.get_policy(parsed_args.policy) policy = client.update_policy( - policy=parsed_args.policy, **policy_attrs) + policy, **policy_attrs) fmt = set_attributes_for_print_detail(policy) # display_columns, columns = _get_columns(obj) @@ -475,7 +483,7 @@ def get_parser(self, prog_name): parser.add_argument( 'policy', metavar='', - help=_('AS Policy ID or name') + help=_('AS Policy ID') ) return parser @@ -494,7 +502,7 @@ def get_parser(self, prog_name): parser.add_argument( 'policy', metavar='', - help=_('AS Policy ID or name') + help=_('AS Policy ID') ) return parser diff --git a/otcextensions/sdk/auto_scaling/v1/_base.py b/otcextensions/sdk/auto_scaling/v1/_base.py index c63026088..3538af915 100644 --- a/otcextensions/sdk/auto_scaling/v1/_base.py +++ b/otcextensions/sdk/auto_scaling/v1/_base.py @@ -60,3 +60,15 @@ def _action(self, session, body): url, # endpoint_override=endpoint_override, json=body) + + def commit(self, session, prepend_key=False, has_body=True, + retry_on_conflict=None, base_path=None): + return \ + super(Resource, self).commit(session, prepend_key=prepend_key, + has_body=has_body, + retry_on_conflict=retry_on_conflict, + base_path=base_path) + + def create(self, session, prepend_key=False, base_path=None, **params): + return super(Resource, self).create(session, prepend_key=prepend_key, + base_path=base_path, **params) diff --git a/otcextensions/sdk/auto_scaling/v1/_proxy.py b/otcextensions/sdk/auto_scaling/v1/_proxy.py index 7c020739c..1600db592 100644 --- a/otcextensions/sdk/auto_scaling/v1/_proxy.py +++ b/otcextensions/sdk/auto_scaling/v1/_proxy.py @@ -307,10 +307,11 @@ def delete_policy(self, policy, ignore_missing=True): return self._delete(_policy.Policy, policy, ignore_missing=ignore_missing) - def find_policy(self, name_or_id, ignore_missing=True): + def find_policy(self, name_or_id, group, ignore_missing=True): """Find a single policy :param name_or_id: The name or ID of a policy + :param group: ID of a group :param bool ignore_missing: When set to ``False`` :class:`~openstack.exceptions.ResourceNotFound` will be raised when the policy does not exist. @@ -319,8 +320,10 @@ def find_policy(self, name_or_id, ignore_missing=True): :returns: ``None`` """ + group = self._get_resource(_group.Group, group) return self._find(_policy.Policy, name_or_id, - ignore_missing=ignore_missing) + ignore_missing=ignore_missing, + group_id=group.id) def execute_policy(self, policy): """execute policy diff --git a/otcextensions/sdk/auto_scaling/v1/config.py b/otcextensions/sdk/auto_scaling/v1/config.py index ff551016a..f14f7ae7f 100644 --- a/otcextensions/sdk/auto_scaling/v1/config.py +++ b/otcextensions/sdk/auto_scaling/v1/config.py @@ -54,7 +54,7 @@ class InstanceConfig(resource.Resource): class Config(_base.Resource): - # resource_key = 'scaling_configuration' + resource_key = 'scaling_configuration' resources_key = 'scaling_configurations' base_path = '/scaling_configuration' # query_marker_key = 'start_number' diff --git a/otcextensions/sdk/auto_scaling/v1/group.py b/otcextensions/sdk/auto_scaling/v1/group.py index 7175be6a8..7f135ec3d 100644 --- a/otcextensions/sdk/auto_scaling/v1/group.py +++ b/otcextensions/sdk/auto_scaling/v1/group.py @@ -26,14 +26,14 @@ class Group(_base.Resource): allow_list = True allow_fetch = True allow_delete = True - allow_update = True + allow_commit = True _query_mapping = resource.QueryParameters( - 'scaling_configuration_id', 'scaling_group_name', 'limit', - scaling_group_name='scaling_group_name', - # status='scaling_group_status', - marker=query_marker_key, - limit='limit' + 'id', 'name', 'limit', 'marker', + 'scaling_configuration_id', + name='scaling_group_name', + status='scaling_group_status', + marker=query_marker_key ) #: Properties @@ -49,9 +49,9 @@ class Group(_base.Resource): #: AutoScaling group detail detail = resource.Body('detail') #: VPC id - (Router Id) - network_id = resource.Body('vpc_id') + router_id = resource.Body('vpc_id') #: network id list - (Subnet) - subnetworks = resource.Body('networks', type=list) + networks = resource.Body('networks', type=list) #: security group id list security_groups = resource.Body('security_groups', type=list) #: Auto Scaling Config ID reference, used for creating instance diff --git a/otcextensions/sdk/auto_scaling/v1/policy.py b/otcextensions/sdk/auto_scaling/v1/policy.py index 81d81b64c..f98b6ae31 100644 --- a/otcextensions/sdk/auto_scaling/v1/policy.py +++ b/otcextensions/sdk/auto_scaling/v1/policy.py @@ -10,6 +10,7 @@ # License for the specific language governing permissions and limitations # under the License. from openstack import resource +from openstack import exceptions from otcextensions.sdk.auto_scaling.v1 import _base @@ -41,8 +42,19 @@ class Action(resource.Resource): #: Scaling trigger action type #: valid values include: ``ADD``, ``REMOVE``, ``SET`` operation = resource.Body('operation') - #: The instance number action for - instance_number = resource.Body('instance_number') + #: Number of instances which will be operated by the action + #: Values from 0 to 200 are possible. + #: Note: Use either instance_number or instance_percentage + #: If nothing of instance_number or instance_percentage is set, the + #: default value is 1. + instance_number = resource.Body('instance_number', type=int) + #: Percentage of instances which are currently there to be operated + #: by the action + #: Values from 0 to 20000 are possible. + #: Note: Use either instance_number or instance_percentage + #: If nothing of instance_number or instance_percentage is set, the default + #: value is 1. + instance_percentage = resource.Body('instance_percentage', type=int) class Policy(_base.Resource): @@ -75,14 +87,14 @@ class Policy(_base.Resource): #: valid values include: ``ALARM``, ``SCHEDULED``, ``RECURRENCE`` type = resource.Body('scaling_policy_type') #: AutoScaling group reference the policy apply to - scaling_group_id = resource.URI('scaling_group_id') + scaling_group_id = resource.Body('scaling_group_id') alarm_id = resource.Body('alarm_id') scheduled_policy = resource.Body('scheduled_policy', type=ScheduledPolicy) scaling_policy_action = resource.Body('scaling_policy_action', type=Action) - cool_down_time = resource.Body('cool_down_time') + cool_down_time = resource.Body('cool_down_time', type=int) create_time = resource.Body('create_time') #: valid values include: ``INSERVICE``, ``PAUSED`` status = resource.Body('policy_status') @@ -101,3 +113,58 @@ def resume(self, session): """resume policy""" body = {"action": "resume"} self._action(session, body) + + @classmethod + def find(cls, session, name_or_id, ignore_missing=True, **params): + """Find a resource by its name or id. + + :param session: The session to use for making this request. + :type session: :class:`~keystoneauth1.adapter.Adapter` + :param name_or_id: This resource's identifier, if needed by + the request. The default is ``None``. + :param bool ignore_missing: When set to ``False`` + :class:`~openstack.exceptions.ResourceNotFound` will be + raised when the resource does not exist. + When set to ``True``, None will be returned when + attempting to find a nonexistent resource. + :param dict params: Any additional parameters to be passed into + underlying methods, such as to + :meth:`~openstack.resource.Resource.existing` + in order to pass on URI parameters. + + :return: The :class:`Resource` object matching the given name or id + or None if nothing matches. + :raises: :class:`openstack.exceptions.DuplicateResource` if more + than one resource is found for this request. + :raises: :class:`openstack.exceptions.ResourceNotFound` if nothing + is found and ignore_missing is ``False``. + """ + session = cls._get_session(session) + # Try to short-circuit by looking directly for a matching ID. + group_id = params.pop('group_id', None) + try: + match = cls.existing( + id=name_or_id, + connection=session._get_connection(), + **params) + return match.fetch(session, **params) + except exceptions.NotFoundException: + pass + + # if ('name' in cls._query_mapping._mapping.keys() + # and 'name' not in params): + params['name'] = name_or_id + + base_path = '/scaling_policy/{id}/list'.format(id=group_id) + data = cls.list(session, + base_path=base_path, + **params) + + result = cls._get_one_match(name_or_id, data) + if result is not None: + return result + + if ignore_missing: + return None + raise exceptions.ResourceNotFound( + "No %s found for %s" % (cls.__name__, name_or_id)) diff --git a/otcextensions/tests/unit/osclient/auto_scaling/v1/fakes.py b/otcextensions/tests/unit/osclient/auto_scaling/v1/fakes.py index 5b12dd175..8a8dc006e 100644 --- a/otcextensions/tests/unit/osclient/auto_scaling/v1/fakes.py +++ b/otcextensions/tests/unit/osclient/auto_scaling/v1/fakes.py @@ -52,7 +52,7 @@ def generate(cls): 'id': 'id-' + uuid.uuid4().hex, 'status': 'SOME STATUS', 'detail': 'detail-' + uuid.uuid4().hex, - 'network_id': 'id-vpc-' + uuid.uuid4().hex, + 'router_id': 'id-vpc-' + uuid.uuid4().hex, } obj = group.Group.existing(**object_info) return obj diff --git a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_activity.py b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_activity.py index 30da58ba4..63132fc85 100644 --- a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_activity.py +++ b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_activity.py @@ -58,10 +58,10 @@ def setUp(self): def test_list_default(self): arglist = [ - '--start_time', '2200-01-01T00:00:00Z', - '--end_time', '2200-01-02T00:00:00Z', + '--start-time', '2200-01-01T00:00:00Z', + '--end-time', '2200-01-02T00:00:00Z', '--limit', '14', - 'group1' + '--group', 'group1' ] verifylist = [ diff --git a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_config.py b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_config.py index f19a953a6..295e900ff 100644 --- a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_config.py +++ b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_config.py @@ -172,7 +172,7 @@ def test_create_ok(self): arglist = [ 'config_name', '--flavor', 'some_flavor', - '--image_id', 'some_image', + '--image-id', 'some_image', '--disk', 'SYS,SSD,10', '--disk', 'DATA,SSD,5', ] diff --git a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_group.py b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_group.py index 6c98e5011..95e3472fb 100644 --- a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_group.py +++ b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_group.py @@ -50,10 +50,19 @@ def setUp(self): def test_list_default(self): arglist = [ + '--name', 'grp', + '--status', 'PAUSED', + '--scaling-configuration-id', '2', + '--limit', '12' ] verifylist = [ + ('name', 'grp'), + ('status', 'PAUSED'), + ('scaling_configuration_id', '2'), + ('limit', 12) ] + # Verify cm is triggereg with default parameters parsed_args = self.check_parser(self.cmd, arglist, verifylist) @@ -65,7 +74,11 @@ def test_list_default(self): # Trigger the action columns, data = self.cmd.take_action(parsed_args) - self.client.groups.assert_called_once_with() + self.client.groups.assert_called_once_with( + name='grp', + status='PAUSED', + scaling_configuration_id='2', + limit=12) self.assertEqual(self.columns, columns) self.assertEqual(self.data, list(data)) @@ -73,7 +86,7 @@ def test_list_default(self): class TestShowAutoScalingGroup(TestAutoScalingGroup): - columns = ('create_time', 'detail', 'id', 'name', 'network_id', 'status') + columns = ('create_time', 'detail', 'id', 'name', 'router_id', 'status') _group = fakes.FakeGroup.create_one() @@ -82,7 +95,7 @@ class TestShowAutoScalingGroup(TestAutoScalingGroup): _group.detail, _group.id, _group.name, - _group.network_id, + _group.router_id, _group.status, ) @@ -119,7 +132,7 @@ def test_show_default(self): class TestCreateAutoScalingGroup(TestAutoScalingGroup): - columns = ('create_time', 'detail', 'id', 'name', 'network_id', 'status') + columns = ('create_time', 'detail', 'id', 'name', 'router_id', 'status') _group = fakes.FakeGroup.create_one() @@ -128,7 +141,7 @@ class TestCreateAutoScalingGroup(TestAutoScalingGroup): _group.detail, _group.id, _group.name, - _group.network_id, + _group.router_id, _group.status, ) @@ -141,23 +154,23 @@ def setUp(self): def test_create(self): arglist = [ - '--desire_instance_number', '10', - '--min_instance_number', '1', - '--max_instance_number', '15', - '--cool_down_time', '1', - '--availability_zone', 'eu-1', - '--availability_zone', 'eu-2', - '--subnet', 'sub1', - '--subnet', 'sub2', - '--router', 'vpc-1', - '--security_group', 'sg1', - '--security_group', 'sg2', - '--lb_listener_id', 'lb1', - '--lbaas_listener', 'lbas1:14', - '--lbaas_listener', 'lbas2:15:10', - '--audit_method', 'some_method', - '--audit_time', '15', - '--terminate_policy', 'pol', + '--desire-instance-number', '10', + '--min-instance-number', '1', + '--max-instance-number', '15', + '--cool-down-time', '1', + '--availability-zone', 'eu-1', + '--availability-zone', 'eu-2', + '--network-id', 'sub1', + '--network-id', 'sub2', + '--router-id', 'vpc-1', + '--security-group', 'sg1', + '--security-group', 'sg2', + '--lb-listener-id', 'lb1', + '--lbaas-listener', 'lbas1:14', + '--lbaas-listener', 'lbas2:15:10', + '--audit-method', 'some_method', + '--audit-time', '15', + '--terminate-policy', 'pol', '--notification', 'EMAIL', '--notification', 'SMS', @@ -169,9 +182,9 @@ def test_create(self): ('max_instance_number', 15), ('cool_down_time', 1), ('availability_zone', ['eu-1', 'eu-2']), - ('subnet', ['sub1', 'sub2']), + ('network_id', ['sub1', 'sub2']), ('security_group', ['sg1', 'sg2']), - ('router', 'vpc-1'), + ('router_id', 'vpc-1'), ('lb_listener_id', 'lb1'), ('lbaas_listener', ['lbas1:14', 'lbas2:15:10']), ('audit_method', 'some_method'), @@ -208,7 +221,7 @@ def test_create(self): networks=[{'id': 'sub1'}, {'id': 'sub2'}], notifications=['EMAIL', 'SMS'], security_groups=[{'id': 'sg1'}, {'id': 'sg2'}], - vpc_id='vpc-1' + router_id='vpc-1' ) self.assertEqual(self.columns, columns) @@ -245,7 +258,7 @@ def test_sdelete(self): class TestUpdateAutoScalingGroup(TestAutoScalingGroup): - columns = ('create_time', 'detail', 'id', 'name', 'network_id', 'status') + columns = ('create_time', 'detail', 'id', 'name', 'router_id', 'status') _group = fakes.FakeGroup.create_one() @@ -254,7 +267,7 @@ class TestUpdateAutoScalingGroup(TestAutoScalingGroup): _group.detail, _group.id, _group.name, - _group.network_id, + _group.router_id, _group.status, ) @@ -267,23 +280,23 @@ def setUp(self): def test_create(self): arglist = [ - '--desire_instance_number', '10', - '--min_instance_number', '1', - '--max_instance_number', '15', - '--cool_down_time', '1', - '--availability_zone', 'eu-1', - '--availability_zone', 'eu-2', - '--subnetwork', 'sub1', - '--subnetwork', 'sub2', - '--network_id', 'vpc-1', - '--security_group', 'sg1', - '--security_group', 'sg2', - '--lb_listener_id', 'lb1', - '--lbaas_listener', 'lbas1:14', - '--lbaas_listener', 'lbas2:15:10', - '--audit_method', 'some_method', - '--audit_time', '15', - '--terminate_policy', 'pol', + '--desire-instance-number', '10', + '--min-instance-number', '1', + '--max-instance-number', '15', + '--cool-down-time', '1', + '--availability-zone', 'eu-1', + '--availability-zone', 'eu-2', + '--network-id', 'sub1', + '--network-id', 'sub2', + '--router-id', 'vpc-1', + '--security-group', 'sg1', + '--security-group', 'sg2', + '--lb-listener-id', 'lb1', + '--lbaas-listener', 'lbas1:14', + '--lbaas-listener', 'lbas2:15:10', + '--audit-method', 'some_method', + '--audit-time', '15', + '--terminate-policy', 'pol', '--notification', 'EMAIL', '--notification', 'SMS', @@ -295,9 +308,9 @@ def test_create(self): ('max_instance_number', 15), ('cool_down_time', 1), ('availability_zone', ['eu-1', 'eu-2']), - ('subnetwork', ['sub1', 'sub2']), + ('network_id', ['sub1', 'sub2']), ('security_group', ['sg1', 'sg2']), - ('network_id', 'vpc-1'), + ('router_id', 'vpc-1'), ('lb_listener_id', 'lb1'), ('lbaas_listener', ['lbas1:14', 'lbas2:15:10']), ('audit_method', 'some_method'), @@ -314,10 +327,15 @@ def test_create(self): self._group ] + self.client.find_group.side_effect = [ + self._group + ] + # Trigger the action columns, data = self.cmd.take_action(parsed_args) self.client.update_group.assert_called_with( + self._group, available_zones=['eu-1', 'eu-2'], cool_down_time=1, desire_instance_number=10, @@ -330,11 +348,10 @@ def test_create(self): {'id': 'lbas2', 'protocol_port': '15', 'weight': '10'}], max_instance_number=15, min_instance_number=1, - group='test_name', networks=[{'id': 'sub1'}, {'id': 'sub2'}], notifications=['EMAIL', 'SMS'], security_groups=[{'id': 'sg1'}, {'id': 'sg2'}], - vpc_id='vpc-1' + router_id='vpc-1' ) self.assertEqual(self.columns, columns) diff --git a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_instance.py b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_instance.py index 0fd9b4dc0..9b94ea5d0 100644 --- a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_instance.py +++ b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_instance.py @@ -57,9 +57,9 @@ def setUp(self): def test_list(self): arglist = [ - 'grp', - '--life_cycle_state', 'lc', - '--health_status', 'hs', + '--group', 'grp', + '--life-cycle-state', 'lc', + '--health-status', 'hs', '--limit', '12' ] @@ -111,7 +111,7 @@ def setUp(self): def test_remove(self): arglist = [ 'Instance1', - '--delete_instance' + '--delete-instance' ] verifylist = [ ('instance', 'Instance1'), @@ -140,10 +140,10 @@ def setUp(self): def test_wrong_action(self): arglist = [ - 'grp1', + '--group', 'grp1', 'ADD1', 'Instance1', - '--delete_instance', + '--delete-instance', ] verifylist = [ ('instance', ['Instance1']), @@ -159,7 +159,7 @@ def test_wrong_action(self): def test_add(self): arglist = [ - 'grp1', + '--group', 'grp1', 'ADD', 'Instance1', ] @@ -185,11 +185,11 @@ def test_add(self): def test_remove(self): arglist = [ - 'grp1', + '--group', 'grp1', 'REMOVE', 'Instance1', 'Instance2', - '--delete_instance', + '--delete-instance', ] verifylist = [ ('instance', ['Instance1', 'Instance2']), @@ -214,7 +214,7 @@ def test_remove(self): def test_protect(self): arglist = [ - 'grp1', + '--group', 'grp1', 'protect', 'Instance1', 'Instance2', @@ -241,7 +241,7 @@ def test_protect(self): def test_unprotect(self): arglist = [ - 'grp1', + '--group', 'grp1', 'unProtect', 'Instance1', 'Instance2', diff --git a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_policy.py b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_policy.py index 8e0a668b5..feab2f710 100644 --- a/otcextensions/tests/unit/osclient/auto_scaling/v1/test_policy.py +++ b/otcextensions/tests/unit/osclient/auto_scaling/v1/test_policy.py @@ -171,15 +171,15 @@ def test_create(self): arglist = [ '--group', 'group1', '--type', 'ALARM', - '--cool_down_time', '1', - '--alarm_id', 'alarm1', - '--action_operation', 'ADD', - '--action_instance_number', '7', - '--launch_time', 'launch_time1', - '--recurrence_type', 'recurrence_type1', - '--recurrence_value', 'recurrence_value1', - '--start_time', 'st1', - '--end_time', 'et1', + '--cool-down-time', '1', + '--alarm-id', 'alarm1', + '--action-operation', 'ADD', + '--action-instance-number', '7', + '--launch-time', 'launch_time1', + '--recurrence-type', 'recurrence_type1', + '--recurrence-value', 'recurrence_value1', + '--start-time', 'st1', + '--end-time', 'et1', 'test_name' ] @@ -292,15 +292,15 @@ def test_create(self): arglist = [ '--group', 'group1', '--type', 'ALARM', - '--cool_down_time', '1', - '--alarm_id', 'alarm1', - '--action_operation', 'ADD', - '--action_instance_number', '7', - '--launch_time', 'launch_time1', - '--recurrence_type', 'recurrence_type1', - '--recurrence_value', 'recurrence_value1', - '--start_time', 'st1', - '--end_time', 'et1', + '--cool-down-time', '1', + '--alarm-id', 'alarm1', + '--action-operation', 'ADD', + '--action-instance-number', '7', + '--launch-time', 'launch_time1', + '--recurrence-type', 'recurrence_type1', + '--recurrence-value', 'recurrence_value1', + '--start-time', 'st1', + '--end-time', 'et1', 'policy1' ] @@ -326,13 +326,17 @@ def test_create(self): self._obj ] + self.client.get_policy.side_effect = [ + self._obj + ] + # Trigger the action columns, data = self.cmd.take_action(parsed_args) self.client.update_policy.assert_called_with( + self._obj, alarm_id='alarm1', cool_down_time=1, - policy='policy1', scaling_group_id='group1', scaling_policy_action={'operation': 'ADD', 'instance_number': 7}, scheduled_policy={ diff --git a/otcextensions/tests/unit/sdk/auto_scaling/v1/test_group.py b/otcextensions/tests/unit/sdk/auto_scaling/v1/test_group.py index e825cc740..72cb7610d 100644 --- a/otcextensions/tests/unit/sdk/auto_scaling/v1/test_group.py +++ b/otcextensions/tests/unit/sdk/auto_scaling/v1/test_group.py @@ -73,7 +73,7 @@ def test_basic(self): self.assertTrue(sot.allow_list) self.assertTrue(sot.allow_create) self.assertTrue(sot.allow_get) - self.assertTrue(sot.allow_update) + self.assertTrue(sot.allow_commit) self.assertTrue(sot.allow_delete) def test_make_it(self): diff --git a/otcextensions/tests/unit/sdk/auto_scaling/v1/test_policy.py b/otcextensions/tests/unit/sdk/auto_scaling/v1/test_policy.py index 3e0b220bc..b0a9fcc86 100644 --- a/otcextensions/tests/unit/sdk/auto_scaling/v1/test_policy.py +++ b/otcextensions/tests/unit/sdk/auto_scaling/v1/test_policy.py @@ -137,7 +137,6 @@ def test_create(self): call_args = self.sess.post.call_args_list[0] expected_json = copy.deepcopy(EXAMPLE) - expected_json.pop('scaling_group_id') self.assertEqual('/scaling_policy', call_args[0][0]) self.assertDictEqual(expected_json, call_args[1]['json']) @@ -184,7 +183,6 @@ def test_update(self): expected_json = copy.deepcopy(EXAMPLE) expected_json.pop('scaling_policy_id') - expected_json.pop('scaling_group_id') self.assertEqual( 'scaling_policy/%s' % EXAMPLE['scaling_policy_id'], diff --git a/otcextensions/tests/unit/sdk/auto_scaling/v1/test_proxy.py b/otcextensions/tests/unit/sdk/auto_scaling/v1/test_proxy.py index 248d8212e..467f6227a 100644 --- a/otcextensions/tests/unit/sdk/auto_scaling/v1/test_proxy.py +++ b/otcextensions/tests/unit/sdk/auto_scaling/v1/test_proxy.py @@ -184,10 +184,14 @@ def test_find(self): self._verify2( 'openstack.proxy.Proxy._find', self.proxy.find_policy, - method_args=['pol'], + method_args=['pol', 'group'], + method_kwargs={}, expected_args=[_policy.Policy, 'pol'], expected_kwargs={ - 'ignore_missing': True}) + 'ignore_missing': True, + 'group_id': 'group' + } + ) def test_update(self): self._verify2( diff --git a/setup.cfg b/setup.cfg index a03f17c21..cc13ea867 100644 --- a/setup.cfg +++ b/setup.cfg @@ -121,6 +121,7 @@ openstack.auto_scaling.v1 = as_policy_execute = otcextensions.osclient.auto_scaling.v1.policy:ExecuteAutoScalingPolicy as_policy_enable = otcextensions.osclient.auto_scaling.v1.policy:EnableAutoScalingPolicy as_policy_disable = otcextensions.osclient.auto_scaling.v1.policy:DisableAutoScalingPolicy + as_policy_delete = otcextensions.osclient.auto_scaling.v1.policy:DeleteAutoScalingPolicy as_instance_list = otcextensions.osclient.auto_scaling.v1.instance:ListAutoScalingInstance as_instance_remove = otcextensions.osclient.auto_scaling.v1.instance:RemoveAutoScalingInstance as_instance_batch = otcextensions.osclient.auto_scaling.v1.instance:BatchActionAutoScalingInstance From 33ace9c1b28eddeb23325e64daa5ced0f64dccf6 Mon Sep 17 00:00:00 2001 From: Artem Goncharov Date: Mon, 24 Feb 2020 15:40:00 +0100 Subject: [PATCH 41/42] add unit test changes --- .../unit/osclient/dns/v2/test_recordset.py | 183 ++++++++++++++++++ .../tests/unit/sdk/dns/v2/test_proxy.py | 7 + 2 files changed, 190 insertions(+) diff --git a/otcextensions/tests/unit/osclient/dns/v2/test_recordset.py b/otcextensions/tests/unit/osclient/dns/v2/test_recordset.py index cb63aa25a..30603b4ef 100644 --- a/otcextensions/tests/unit/osclient/dns/v2/test_recordset.py +++ b/otcextensions/tests/unit/osclient/dns/v2/test_recordset.py @@ -74,6 +74,43 @@ def test_default_zone(self): self.assertEqual(self.columns, columns) self.assertEqual(self.data, list(data)) + def test_private_zone(self): + arglist = [ + 'zn', + '--zone-type', 'private' + ] + + verifylist = [ + ('zone', 'zn'), + ('zone_type', 'private') + ] + + # Verify cm is triggereg with default parameters + parsed_args = self.check_parser(self.cmd, arglist, verifylist) + + # Set the response + self.client.api_mock.side_effect = [ + self.objects + ] + self.client.find_zone.side_effect = [ + self._zone + ] + + # Trigger the action + columns, data = self.cmd.take_action(parsed_args) + + self.client.find_zone.assert_called_once_with( + 'zn', + zone_type='private', + ignore_missing=False, + ) + self.client.api_mock.assert_called_once_with( + zone=self._zone + ) + + self.assertEqual(self.columns, columns) + self.assertEqual(self.data, list(data)) + class TestShowRS(fakes.TestDNS): @@ -120,6 +157,53 @@ def test_default(self): # Trigger the action columns, data = self.cmd.take_action(parsed_args) + self.client.find_zone.assert_called_once_with( + 'zone', + ignore_missing=False, + zone_type=None + ) + + self.client.api_mock.assert_called_once_with( + zone=self._zone, + name_or_id='rs' + ) + + self.assertEqual(self.columns, columns) + self.assertEqual(self.data, data) + + def test_private(self): + arglist = [ + 'zone', + 'rs', + '--zone-type', 'private' + ] + + verifylist = [ + ('zone', 'zone'), + ('recordset', 'rs'), + ('zone_type', 'private') + ] + + # Verify cm is triggereg with default parameters + parsed_args = self.check_parser(self.cmd, arglist, verifylist) + + # Set the response + self.client.find_zone.side_effect = [ + self._zone + ] + self.client.api_mock.side_effect = [ + self._data + ] + + # Trigger the action + columns, data = self.cmd.take_action(parsed_args) + + self.client.find_zone.assert_called_once_with( + 'zone', + ignore_missing=False, + zone_type='private' + ) + self.client.api_mock.assert_called_once_with( zone=self._zone, name_or_id='rs' @@ -195,6 +279,60 @@ def test_create(self): self.assertEqual(self.columns, columns) self.assertEqual(self.data, data) + def test_create_private(self): + arglist = [ + 'zn', + '--name', 'rs', + '--description', 'descr', + '--type', 'A', + '--ttl', '500', + '--record', 'a=b', + '--record', 'c=d', + '--zone-type', 'private' + ] + + verifylist = [ + ('zone', 'zn'), + ('name', 'rs'), + ('description', 'descr'), + ('type', 'A'), + ('ttl', 500), + ('record', ['a=b', 'c=d']), + ('zone_type', 'private') + ] + + # Verify cm is triggereg with default parameters + parsed_args = self.check_parser(self.cmd, arglist, verifylist) + + # Set the response + self.client.find_zone.side_effect = [ + self._zone + ] + self.client.api_mock.side_effect = [ + self._data + ] + + # Trigger the action + columns, data = self.cmd.take_action(parsed_args) + + self.client.find_zone.assert_called_once_with( + 'zn', + ignore_missing=False, + zone_type='private' + ) + + self.client.api_mock.assert_called_once_with( + zone=self._zone, + description='descr', + name='rs', + type='A', + ttl=500, + records=['a=b', 'c=d'] + ) + + self.assertEqual(self.columns, columns) + self.assertEqual(self.data, data) + class TestSetRS(fakes.TestDNS): @@ -321,3 +459,48 @@ def test_delete_multiple(self): self.client.api_mock.assert_has_calls(calls) self.assertEqual(2, self.client.api_mock.call_count) + + def test_private(self): + arglist = [ + 'zn', + 't1', + '--zone-type', 'private' + ] + verifylist = [ + ('zone', 'zn'), + ('recordset', ['t1']), + ('zone_type', 'private') + ] + # Verify cm is triggereg with default parameters + parsed_args = self.check_parser(self.cmd, arglist, verifylist) + + # Set the response + self.client.find_zone.side_effect = [ + self._zone + ] + + self.client.find_recordset.side_effect = [self._rs, self._rs] + self.client.api_mock.side_effect = [{}, {}] + + # Trigger the action + self.cmd.take_action(parsed_args) + + self.client.find_zone.assert_called_once_with( + 'zn', + ignore_missing=False, + zone_type='private' + ) + + find_calls = [ + mock.call(zone=self._zone, name_or_id='t1', ignore_missing=False), + ] + + self.client.find_recordset.assert_has_calls(find_calls) + + calls = [ + mock.call(zone=self._zone, recordset=self._rs, + ignore_missing=False), + ] + + self.client.api_mock.assert_has_calls(calls) + self.assertEqual(1, self.client.api_mock.call_count) diff --git a/otcextensions/tests/unit/sdk/dns/v2/test_proxy.py b/otcextensions/tests/unit/sdk/dns/v2/test_proxy.py index d2181b384..c04ead73a 100644 --- a/otcextensions/tests/unit/sdk/dns/v2/test_proxy.py +++ b/otcextensions/tests/unit/sdk/dns/v2/test_proxy.py @@ -39,6 +39,13 @@ def test_zone_delete(self): def test_zone_find(self): self.verify_find(self.proxy.find_zone, zone.Zone) + def test_zone_find_private(self): + self.verify_find(self.proxy.find_zone, zone.Zone, + method_kwargs={ + 'p1': 'v1' + }, + expected_kwargs={'p1': 'v1'}) + def test_zone_get(self): self.verify_get(self.proxy.get_zone, zone.Zone) From d3d4cfec54642774c064bddcefc39597e007c5a3 Mon Sep 17 00:00:00 2001 From: Artem Goncharov Date: Mon, 24 Feb 2020 15:43:41 +0100 Subject: [PATCH 42/42] extend help message for DNS zone list --- otcextensions/osclient/dns/v2/zone.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/otcextensions/osclient/dns/v2/zone.py b/otcextensions/osclient/dns/v2/zone.py index 7f7f5769a..f9ed3616a 100644 --- a/otcextensions/osclient/dns/v2/zone.py +++ b/otcextensions/osclient/dns/v2/zone.py @@ -53,7 +53,7 @@ def get_parser(self, prog_name): metavar='{' + ','.join(ZONE_TYPES) + '}', type=lambda s: s.lower(), choices=ZONE_TYPES, - help=_('Zone type.') + help=_('Zone type. Default lists only public zones.') ) return parser