diff --git a/doc/source/configuring.rst b/doc/source/configuring.rst new file mode 100644 index 0000000000..c0aabac1a0 --- /dev/null +++ b/doc/source/configuring.rst @@ -0,0 +1,58 @@ +.. + Copyright 2016 Hewlett Packard Enterprise Development Company LP + 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. + +Configuration +============= + +Magnum has a number of configuration options which will be detailed here. + +Magnum Config +------------- + +The magnum configuration file is called ``magnum.conf``. + +Magnum Pipeline +--------------- + +The pipeline details are contained in ``api-paste.ini``. + +Healthcheck Middleware +~~~~~~~~~~~~~~~~~~~~~~ + +This piece of middleware creates an endpoint that allows a load balancer +to probe if the API endpoint should be available at the node or not. + +The healthcheck middleware should be placed early in the pipeline. Which +is located in your ``api-paste.ini`` under a section called +``[filter:healthcheck]``. It should look like this:: + + [filter:healthcheck] + paste.filter_factory = oslo_middleware:Healthcheck.factory + backends = disable_by_file + disable_by_file_path = /etc/magnum/healthcheck_disable + +The main pipeline using this filter should look something like this also +defined in the ``api-paste.ini``:: + + [pipeline:main] + pipeline = cors healthcheck request_id authtoken api_v1 + +If you wish to disable a middleware without taking it out of the +pipeline, you can create a file under the file path defined by +``disable_by_file_path`` ie. ``/etc/magnum/healthcheck_disable``. + +For more information see +`oslo.middleware `_. diff --git a/doc/source/index.rst b/doc/source/index.rst index 257042aba8..16a8751cec 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -98,3 +98,4 @@ Work In Progress troubleshooting-guide.rst userguide.rst + configuring.rst diff --git a/etc/magnum/api-paste.ini b/etc/magnum/api-paste.ini index 067dfa4bc8..68f3b25b9a 100644 --- a/etc/magnum/api-paste.ini +++ b/etc/magnum/api-paste.ini @@ -1,5 +1,5 @@ [pipeline:main] -pipeline = cors request_id authtoken api_v1 +pipeline = cors healthcheck request_id authtoken api_v1 [app:api_v1] paste.app_factory = magnum.api.app:app_factory @@ -14,3 +14,8 @@ paste.filter_factory = oslo_middleware:RequestId.factory [filter:cors] paste.filter_factory = oslo_middleware.cors:filter_factory oslo_config_project = magnum + +[filter:healthcheck] +paste.filter_factory = oslo_middleware:Healthcheck.factory +backends = disable_by_file +disable_by_file_path = /etc/magnum/healthcheck_disable diff --git a/magnum/tests/unit/api/controllers/auth-paste.ini b/magnum/tests/unit/api/controllers/auth-paste.ini index 498fb0b74d..237faf278e 100644 --- a/magnum/tests/unit/api/controllers/auth-paste.ini +++ b/magnum/tests/unit/api/controllers/auth-paste.ini @@ -1,5 +1,5 @@ [pipeline:main] -pipeline = cors request_id authtoken api_v1 +pipeline = cors healthcheck request_id authtoken api_v1 [app:api_v1] paste.app_factory = magnum.api.app:app_factory @@ -16,3 +16,8 @@ oslo_config_project = magnum latent_allow_methods = GET, PUT, POST, DELETE, PATCH latent_allow_headers = X-Auth-Token, X-Identity-Status, X-Roles, X-Service-Catalog, X-User-Id, X-Tenant-Id, X-OpenStack-Request-ID latent_expose_headers = X-Auth-Token, X-Subject-Token, X-Service-Token, X-OpenStack-Request-ID + +[filter:healthcheck] +paste.filter_factory = oslo_middleware:Healthcheck.factory +backends = disable_by_file +disable_by_file_path = /tmp/magnum_healthcheck_disable diff --git a/magnum/tests/unit/api/controllers/auth-root-access.ini b/magnum/tests/unit/api/controllers/auth-root-access.ini index 37971ec03b..cd832e1598 100644 --- a/magnum/tests/unit/api/controllers/auth-root-access.ini +++ b/magnum/tests/unit/api/controllers/auth-root-access.ini @@ -1,5 +1,5 @@ [pipeline:main] -pipeline = cors request_id authtoken api_v1 +pipeline = cors healthcheck request_id authtoken api_v1 [app:api_v1] paste.app_factory = magnum.api.app:app_factory @@ -17,3 +17,8 @@ oslo_config_project = magnum latent_allow_methods = GET, PUT, POST, DELETE, PATCH latent_allow_headers = X-Auth-Token, X-Identity-Status, X-Roles, X-Service-Catalog, X-User-Id, X-Tenant-Id, X-OpenStack-Request-ID latent_expose_headers = X-Auth-Token, X-Subject-Token, X-Service-Token, X-OpenStack-Request-ID + +[filter:healthcheck] +paste.filter_factory = oslo_middleware:Healthcheck.factory +backends = disable_by_file +disable_by_file_path = /tmp/magnum_healthcheck_disable diff --git a/magnum/tests/unit/api/controllers/auth-v1-access.ini b/magnum/tests/unit/api/controllers/auth-v1-access.ini index 4f88187934..b6b3981dea 100644 --- a/magnum/tests/unit/api/controllers/auth-v1-access.ini +++ b/magnum/tests/unit/api/controllers/auth-v1-access.ini @@ -1,5 +1,5 @@ [pipeline:main] -pipeline = cors request_id authtoken api_v1 +pipeline = cors healthcheck request_id authtoken api_v1 [app:api_v1] paste.app_factory = magnum.api.app:app_factory @@ -17,3 +17,8 @@ oslo_config_project = magnum latent_allow_methods = GET, PUT, POST, DELETE, PATCH latent_allow_headers = X-Auth-Token, X-Identity-Status, X-Roles, X-Service-Catalog, X-User-Id, X-Tenant-Id, X-OpenStack-Request-ID latent_expose_headers = X-Auth-Token, X-Subject-Token, X-Service-Token, X-OpenStack-Request-ID + +[filter:healthcheck] +paste.filter_factory = oslo_middleware:Healthcheck.factory +backends = disable_by_file +disable_by_file_path = /tmp/magnum_healthcheck_disable diff --git a/magnum/tests/unit/api/controllers/test_root.py b/magnum/tests/unit/api/controllers/test_root.py index 727ee4df98..b366904676 100644 --- a/magnum/tests/unit/api/controllers/test_root.py +++ b/magnum/tests/unit/api/controllers/test_root.py @@ -14,6 +14,12 @@ import mock from oslo_config import cfg from webob import exc as webob_exc +try: + import configparser as ConfigParser +except ImportError: + import ConfigParser +import shutil +import tempfile import webtest from magnum.api import app @@ -163,6 +169,49 @@ class TestRootController(api_base.FunctionalTest): self.assertEqual(401, response.status_int) +class TestHeathcheck(api_base.FunctionalTest): + def setUp(self): + self.addCleanup(self.remove_files) + super(TestHeathcheck, self).setUp() + + # Create Temporary file + self.tempdir = tempfile.mkdtemp() + paste_ini = "magnum/tests/unit/api/controllers/auth-paste.ini" + + # Read current file and create new one + config = ConfigParser.RawConfigParser() + config.read(self.get_path(paste_ini)) + config.set('filter:healthcheck', + 'disable_by_file_path', + self.tempdir + "/disable") + with open(self.tempdir + "/paste.ini", 'wt') as configfile: + config.write(configfile) + + # Set config and create app + cfg.CONF.set_override("api_paste_config", + self.tempdir + "/paste.ini", + group="api") + self.app = webtest.TestApp(app.load_app()) + + def remove_files(self): + shutil.rmtree(self.tempdir, ignore_errors=True) + + def test_healthcheck_enabled(self): + # Check the healthcheck works + response = self.app.get('/healthcheck') + self.assertEqual(200, response.status_int) + self.assertEqual(b"OK", response.body) + + def test_healthcheck_disable_file(self): + # Create the file that disables healthcheck + fo = open(self.tempdir + "/disable", 'a') + fo.close() + + response = self.app.get('/healthcheck', expect_errors=True) + self.assertEqual(503, response.status_int) + self.assertEqual(b"DISABLED BY FILE", response.body) + + class TestV1Routing(api_base.FunctionalTest): def test_route_checks_version(self):