From 851227deeaf9454f45535c14b03fed79078d3ec3 Mon Sep 17 00:00:00 2001 From: Lingxian Kong Date: Tue, 5 Sep 2017 12:21:53 +1200 Subject: [PATCH] Add devstack installation doc Change-Id: I7db6a270489aa7f8191ab1db7c6107bfa853e51f --- devstack/plugin.sh | 6 +- doc/README.rst | 27 ++++ doc/source/{ => contributor}/contributing.rst | 2 +- .../development-environment-devstack.rst | 109 +++++++++++++ doc/source/contributor/index.rst | 37 +++++ doc/source/index.rst | 21 ++- doc/source/installation.rst | 148 ------------------ qinling_tempest_plugin/config.py | 2 +- qinling_tempest_plugin/services/base.py | 15 +- tox.ini | 5 +- 10 files changed, 205 insertions(+), 167 deletions(-) create mode 100644 doc/README.rst rename doc/source/{ => contributor}/contributing.rst (50%) create mode 100644 doc/source/contributor/development-environment-devstack.rst create mode 100644 doc/source/contributor/index.rst delete mode 100644 doc/source/installation.rst diff --git a/devstack/plugin.sh b/devstack/plugin.sh index 7d959850..89396ffa 100755 --- a/devstack/plugin.sh +++ b/devstack/plugin.sh @@ -32,8 +32,8 @@ function install_k8s { function create_qinling_accounts { create_service_user "qinling" "admin" - local qinling_service=$(get_or_create_service "qinling" "function" "Function Service") - qinling_api_url="$QINLING_SERVICE_PROTOCOL://$QINLING_SERVICE_HOST:$QINLING_SERVICE_PORT/v1" + local qinling_service=$(get_or_create_service "qinling" "function-engine" "Function Service") + qinling_api_url="$QINLING_SERVICE_PROTOCOL://$QINLING_SERVICE_HOST:$QINLING_SERVICE_PORT" get_or_create_endpoint $qinling_service \ "$REGION_NAME" \ @@ -41,7 +41,7 @@ function create_qinling_accounts { "$qinling_api_url" \ "$qinling_api_url" - # get or adds 'service' role to 'qinling' on 'demo' project + # get or adds 'service' role to 'qinling' user on 'demo' project get_or_add_user_project_role "service" "qinling" "demo" } diff --git a/doc/README.rst b/doc/README.rst new file mode 100644 index 00000000..531ed25c --- /dev/null +++ b/doc/README.rst @@ -0,0 +1,27 @@ +======================== +Qinling Development Docs +======================== + +Files under this directory tree are used for generating the documentation +for the qinling source code. + +Developer documentation is built to: +http://qinling.readthedocs.io/en/latest/ + +Tools +===== + +Sphinx + The Python Sphinx package is used to generate the documentation output. + Information on Sphinx, including formatting information for RST source + files, can be found in the `Sphinx online documentation + `_. + +Building Documentation +====================== + +Doc builds are performed using tox with the ``docs`` target:: + + % cd .. + % tox -e docs + diff --git a/doc/source/contributing.rst b/doc/source/contributor/contributing.rst similarity index 50% rename from doc/source/contributing.rst rename to doc/source/contributor/contributing.rst index 1728a61c..2aa07077 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributor/contributing.rst @@ -1,4 +1,4 @@ ============ Contributing ============ -.. include:: ../../CONTRIBUTING.rst +.. include:: ../../../CONTRIBUTING.rst diff --git a/doc/source/contributor/development-environment-devstack.rst b/doc/source/contributor/development-environment-devstack.rst new file mode 100644 index 00000000..07622f13 --- /dev/null +++ b/doc/source/contributor/development-environment-devstack.rst @@ -0,0 +1,109 @@ +.. + Copyright 2017 Catalyst IT Ltd + All Rights Reserved. + 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. + +Setting up a development environment with devstack +================================================== + +This page describes how to setup a working development +environment that can be used in deploying qinling on latest releases +of Ubuntu. These instructions assume you are already familiar +with git. Refer to `Getting the code`_ for additional information. + +.. _Getting the code: http://wiki.openstack.org/GettingTheCode + +Following these instructions will allow you to have a fully functional qinling +environment using the devstack project (a shell script to build +complete OpenStack development environments) on Ubuntu 16.04. + +Configuring devstack with qinling +--------------------------------- + +Qinling can be enabled in devstack by using the plug-in based interface it +offers. + +.. note:: + + The following steps have been fully verified only on Ubuntu 16.04. + +Start by cloning the devstack repository: + +:: + + git clone https://github.com/openstack-dev/devstack + +Change to devstack directory: + +:: + + cd devstack/ + +Copy the ``local.conf`` sample file to the upper level directory: + +:: + + cp samples/local.conf . + +Enable the qinling plugin adding the following lines to the end of the +``local.conf`` file: + +:: + + ENABLED_SERVICES=rabbit,mysql,key,tempest + enable_plugin qinling https://github.com/openstack/qinling + LIBS_FROM_GIT="python-qinlingclient" + +Running devstack +---------------- + +.. note:: + + Before running devstack, make sure there is a loopback device defined in + ``/etc/hosts`` file, ``127.0.1.1 localhost`` is recommended, any line + including '127.0.0.1' will be deleted automatically during devstack running. + +Run the ``stack.sh`` script: + +:: + + ./stack.sh + +After it completes, verify qinling service is installed properly: + +.. code-block:: console + + $ source openrc admin admin + $ openstack service list + +----------------------------------+----------+----------+ + | ID | Name | Type | + +----------------------------------+----------+----------+ + | 60145bf464f943aa88613026bd6aa5e3 | qinling | function | + | 750ec7b067b7465bab2389e331f826de | keystone | identity | + +----------------------------------+----------+----------+ + $ openstack runtime list --print-empty + +----+------+-------+--------+-------------+------------+------------+------------+ + | Id | Name | Image | Status | Description | Project_id | Created_at | Updated_at | + +----+------+-------+--------+-------------+------------+------------+------------+ + +----+------+-------+--------+-------------+------------+------------+------------+ + +Kubernetes Integration +---------------------- + +By default, Qinling uses Kubernetes as its orchestrator backend, so a k8s +all-in-one environment (and some other related tools, e.g. kubectl) is also +setup during devstack installation. + +The idea and most of the scripts are coming from +`OpenStack-Helm `_ +project originally, but may be probably changed as the project evolving in +future. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 00000000..d45d21ad --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,37 @@ +.. + Copyright 2010-2011 United States Government as represented by the + Administrator of the National Aeronautics and Space Administration. + All Rights Reserved. + + 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. + +Contributor/Developer Guide +=========================== + +In this section you will find information helpful for contributing to qinling +project. + + +Programming HowTos and Tutorials +-------------------------------- +.. toctree:: + :maxdepth: 2 + + development-environment-devstack + contributing + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`search` diff --git a/doc/source/index.rst b/doc/source/index.rst index 2f2e84d6..3eb5e48d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,11 +13,11 @@ Welcome to Qinling's documentation! North and South China and support a huge variety of plant and wildlife, some of which is found nowhere else on Earth. -Qinling is Function as a Service for OpenStack. This project aims to provide a -platform to support serverless functions (like AWS Lambda). Qinling supports -different container orchestration platforms (Kubernetes/Swarm, etc.) and -different function package storage backends (local/Swift/S3) by nature using -plugin mechanism. +Qinling is an OpenStack project to provide "Function as a service". This +project aims to provide a platform to support serverless functions (like AWS +Lambda). Qinling supports different container orchestration platforms +(Kubernetes/Swarm, etc.) and different function package storage backends +(local/Swift/S3) by nature using plugin mechanism. * Free software: Apache license * Documentation: http://qinling.readthedocs.io/ @@ -26,6 +26,7 @@ plugin mechanism. * Bug Track: http://bugs.launchpad.net/qinling * IRC channel on Freenode: #openstack-qinling + Table of Contents ================= @@ -33,8 +34,14 @@ Table of Contents :maxdepth: 1 quick_start - installation - contributing + +Contributor/Developer Docs +========================== + +.. toctree:: + :maxdepth: 1 + + contributor/index Indices and tables ================== diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index 6f4813c5..00000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,148 +0,0 @@ -Qinling Installation Guide -========================== - -Prerequisites -~~~~~~~~~~~~~ - -It is necessary to install some specific system libs for installing Qinling. -They can be installed on most popular operating system using their package -manager (for Ubuntu - *apt*, for Fedora - *dnf*, CentOS - *yum*, for Mac OS - -*brew* or *macports*). -The list of needed packages is shown below: - -1. **python-dev** -2. **python-setuptools** -3. **python-pip** -4. **libffi-dev** -5. **libxslt1-dev (or libxslt-dev)** -6. **libxml2-dev** -7. **libyaml-dev** -8. **libssl-dev** - -In case of Ubuntu, just run:: - - $ apt-get install -y python-dev python-setuptools python-pip libffi-dev libxslt1-dev \ - libxml2-dev libyaml-dev libssl-dev - -**NOTE:** **Qinling can be used without authentication at all or it can work -with OpenStack.** In case of OpenStack, it works **only on Keystone v3**, make -sure **Keystone v3** is installed. - -Installation -~~~~~~~~~~~~ - -First of all, clone the repo and go to the repo directory:: - - $ git clone https://github.com/openstack/qinling.git - $ cd qinling - -Generate config:: - - $ tox -egenconfig - -Configure Qinling as needed. The configuration file is located in -``etc/qinling.conf.sample``. You will need to modify the configuration options -and then copy it into ``/etc/qinling/qinling.conf``. -For details see :doc:`Qinling Configuration Guide ` - -**Virtualenv installation**:: - - $ tox - -This will install necessary virtual environments and run all the project tests. -Installing virtual environments may take significant time (~10-15 mins). - -**Local installation**:: - - $ pip install -e . - -or:: - - $ pip install -r requirements.txt - $ python setup.py install - -**NOTE**: Differences *pip install -e* and *setup.py install*. **pip install -e** -works very similarly to **setup.py install** or the EasyInstall tool, except -that it doesn’t actually install anything. Instead, it creates a special -.egg-link file in the deployment directory, that links to your project’s -source code. - -Before the first run -~~~~~~~~~~~~~~~~~~~~ - -After installation you will see **qinling-server** and **qinling-db-manage** commands -in your environment, either in system or virtual environment. - -**NOTE**: In case of using **virtualenv**, all Qinling related commands available via -**tox -evenv --**. For example, *qinling-server* is available via -*tox -evenv -- qinling-server*. - -**qinling-db-manage** command can be used for migrations. - -For updating the database to the latest revision type:: - - $ qinling-db-manage --config-file upgrade head - -Before starting Qinling server, run *qinling-db-manage populate* command. -It prepares the DB, creates in it with all standard actions and standard -workflows which Qinling provides for all Qinling users.:: - - $ qinling-db-manage --config-file populate - -For more detailed information about *qinling-db-manage* script please see :doc:`Qinling Upgrade Guide `. - -**NOTE**: For users who want a dry run with **SQLite** database backend(not -used in production), *qinling-db-manage* is not recommended for database -initialization because of `SQLite limitations `_. -Please use sync_db script described below instead for database initialization. - -**If you use virtualenv**:: - - $ tools/sync_db.sh --config-file - -**Or run sync_db directly**:: - - $ python tools/sync_db.py --config-file - -Running Qinling API server -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To run Qinling API server perform the following command in a shell:: - - $ qinling-server --server api --config-file - -Running Qinling Engines -~~~~~~~~~~~~~~~~~~~~~~~ - -To run Qinling Engine perform the following command in a shell:: - - $ qinling-server --server engine --config-file - -Running Qinling Task Executors -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To run Qinling Task Executor instance perform the following command in a shell:: - - $ qinling-server --server executor --config-file - -Note that at least one Engine instance and one Executor instance should be -running so that workflow tasks are processed by Qinling. - -Running Multiple Qinling Servers Under the Same Process -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To run more than one server (API, Engine, or Task Executor) on the same process, -perform the following command in a shell:: - - $ qinling-server --server api,engine --config-file - -The --server command line option can be a comma delimited list. The valid -options are "all" (by default if not specified) or any combination of "api", -"engine", and "executor". It's important to note that the "fake" transport for -the rpc_backend defined in the config file should only be used if "all" the -Qinling servers are launched on the same process. Otherwise, messages do not -get delivered if the Qinling servers are launched on different processes -because the "fake" transport is using an in process queue. - -Qinling Client Installation -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Please refer to :doc:`Qinling Client / CLI Guide ` diff --git a/qinling_tempest_plugin/config.py b/qinling_tempest_plugin/config.py index 7438081a..ec82b1b0 100644 --- a/qinling_tempest_plugin/config.py +++ b/qinling_tempest_plugin/config.py @@ -33,7 +33,7 @@ QinlingGroup = [ "is found in the service catalog, the first found one is " "used."), cfg.StrOpt("catalog_type", - default="function", + default="function-engine", help="Catalog type of the Qinling service."), cfg.StrOpt('endpoint_type', default='publicURL', diff --git a/qinling_tempest_plugin/services/base.py b/qinling_tempest_plugin/services/base.py index 68687c46..2aa95f9c 100644 --- a/qinling_tempest_plugin/services/base.py +++ b/qinling_tempest_plugin/services/base.py @@ -22,23 +22,26 @@ class QinlingClientBase(rest_client.RestClient): super(QinlingClientBase, self).__init__(auth_provider, **kwargs) self.runtimes = [] + self.functions = [] - def get_list_objs(self, url_path): - resp, body = self.get(url_path) + def get_list_objs(self, obj): + resp, body = self.get('/v1/%s' % obj) return resp, json.loads(body) def delete_obj(self, obj, id): - return self.delete('{obj}/{id}'.format(obj=obj, id=id)) + return self.delete('/v1/{obj}/{id}'.format(obj=obj, id=id)) def get_obj(self, obj, id): - resp, body = self.get('{obj}/{id}'.format(obj=obj, id=id)) + resp, body = self.get('/v1/{obj}/{id}'.format(obj=obj, id=id)) return resp, json.loads(body) - def post_json(self, url_path, obj, extra_headers={}): + def post_json(self, obj, req_body, extra_headers={}): headers = {"Content-Type": "application/json"} headers = dict(headers, **extra_headers) - resp, body = self.post(url_path, json.dumps(obj), headers=headers) + url_path = '/v1/%s' % obj + + resp, body = self.post(url_path, json.dumps(req_body), headers=headers) return resp, json.loads(body) diff --git a/tox.ini b/tox.ini index c621e486..072f44ca 100644 --- a/tox.ini +++ b/tox.ini @@ -34,7 +34,10 @@ commands = {posargs} commands = python setup.py test --coverage --testr-args='{posargs}' [testenv:docs] -commands = python setup.py build_sphinx +whitelist_externals = rm +commands = + rm -rf doc/build + python setup.py build_sphinx [testenv:releasenotes] commands =