From 0685f75d97ce273e8e1b7aae9798ad7ff50525a4 Mon Sep 17 00:00:00 2001
From: Tin Lam <tin@irrational.io>
Date: Wed, 29 Nov 2017 16:20:07 -0600
Subject: [PATCH] Spec: Add nginx sidecar

This specification proposes to add an nginx sidecar container to support
TLS offloading and termination.

Change-Id: I6d7e19539b5411d8ab15dc2d39e2051da1cce126
External-tracking: F#47
---
 doc/source/specs/index.rst         |  3 +-
 doc/source/specs/nginx-sidecar.rst | 71 ++++++++++++++++++++++++++++++
 2 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 doc/source/specs/nginx-sidecar.rst

diff --git a/doc/source/specs/index.rst b/doc/source/specs/index.rst
index 1d0c0dde17..2600e6b01b 100644
--- a/doc/source/specs/index.rst
+++ b/doc/source/specs/index.rst
@@ -4,12 +4,13 @@ Specifications
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    developer-environment.rst
    osh-lma-stack.rst
    specifications.rst
    template.rst
    neutron-multiple-sdns.rst
+   nginx-sidecar.rst
    support-linux-bridge-on-neutron.rst
    fluentbit-fluentd-architecture.rst
diff --git a/doc/source/specs/nginx-sidecar.rst b/doc/source/specs/nginx-sidecar.rst
new file mode 100644
index 0000000000..b66bde9721
--- /dev/null
+++ b/doc/source/specs/nginx-sidecar.rst
@@ -0,0 +1,71 @@
+=============
+Nginx Sidecar
+=============
+
+Blueprint: https://blueprints.launchpad.net/openstack-helm/+spec/nginx-sidecar
+
+Problem Description
+===================
+
+In a secured deployment, TLS certificates are used to protect the transports
+amongst the various components.  In some cases, this requires additional
+mechanism to handle TLS offloading and to terminate the connection gracefully:
+
+* services do not handle TLS offloading and termination,
+* services whose native handling of TLS offloading and termination cause major
+  performance impact, for example, eventlet.
+
+Proposed Change
+===============
+
+This specification proposes to add a nginx sidecar container to the
+pod for service that requires the tls offloading. The nginx can be used
+to handle the TLS offoading and terminate the TLS connection, and routes
+the traffic to the service via localhost (127.0.0.1).
+
+Security Impact
+---------------
+
+This enhances the system's security design by allowing pods with services that
+cannot natively manage TLS to secure the traffic to the service pod.
+
+Performance Impact
+------------------
+
+There is no significant performance impact as the traffic will be locally
+routed (via 127.0.0.1) and may potentially improve performance for services
+whose native TLS handling is inefficient.
+
+Alternatives
+------------
+
+* Instead of using nginx, haproxy can be used instead.
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  Pete Birley <pete@port.direct>
+
+Work Items
+----------
+
+* Update ``helm toolkit`` to provide snippet to create the nginx sidecar
+  container for the services that require it.
+* Update service charts to use the updated ``helm toolkit``.
+* Update relevant Documentation.
+
+Testing
+=======
+
+The testing will be performed by the OpenStack-Helm gate to demonstrate
+the sidecar container correctly routes traffic to the correct services.
+
+Documentation Impact
+====================
+
+OpenStack-Helm documentation will be updated to indicate the usage of the
+nginx sidecar.