Healthcheck Middleware

Use the healthcheck middleware from oslo_middleware. This adds a new
pipeline that depends if /etc/magnum/healthcheck_disable file exists.

The healthcheck middleware is avalible under the /healthcheck URL.

Return values:
200 OK (If the file does not exist)
503 DISABLED BY FILE (If file exists)

Change-Id: I23179d5285831af12de7f392849c490d86a5682e

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 <http://docs.openstack.org/developer/oslo.middleware/api.html#oslo_middleware.Healthcheck>`_.

doc/source/index.rst

@@ -98,3 +98,4 @@ Work In Progress
 
    troubleshooting-guide.rst
    userguide.rst
+   configuring.rst

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

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

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

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

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):