proxy.rst 3.83 KB
Newer Older
qhoangxuan's avatar
qhoangxuan committed
1 2
.. _proxy:

Daniele Venzano's avatar
Daniele Venzano committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
Accessing Zoe through a reverse proxy
=====================================

The Zoe web interface and REST API can be exposed through a reverse proxy. Additionally some support for exposing the web interfaces of running executions is also available, with some constraints.

Configuration
-------------

* reverse-proxy-path : path-portion of the external URL in case Zoe is exposed by the reverse proxy under a path (ex.: /zoe)
* websocket_base : Base URL for websocket connections (ex.: ws://<server_address>)

Accessing ZApps through the Træfik reverse proxy
------------------------------------------------

Zoe contains support for dynamically updating a reverse proxy for giving access to users without exposing internal IP addresses. This support is experimental and comes with several limitations:

* Only web interfaces can be exposed via a reverse proxy
* Only Træfik with a ZooKeeper dynamic configuration backend is supported
* Usually the web application running in the Zoe execution must be informed of the external URL it is exposed with. Zoe exposes an environment variable with this information, but it is up to the ZApp implementation to pass the correct options to the web application.

Configuration
^^^^^^^^^^^^^

* traefik-zk-ips : ZooKeeper addresses for storing dynamic configuration for træfik (ex.: ``z1:2181,z2:2181,z3:2181``)
* traefik-base-url : Base path used in reverse proxy URLs generated for træfik (default is ``/zoe/proxy/``)

ZApp description
^^^^^^^^^^^^^^^^

In the JSON description of ZApps, ports that need to be exposed through the reverse proxy need to have the ``proxy`` property set to ``true``. The property is optional and defaults to false, so by default no ports will be exposed via the reverse proxy.

Environment variables
^^^^^^^^^^^^^^^^^^^^^

ZApps can use the ``REVERSE_PROXY_PATH_<port number>`` environment variable to configure correctly the URL routing of web applications they contain. The value of these variables will be the concatenation of ``traefik-base-url`` and the unique key generated at runtime for each proxied port.

39
Access ZApps through Ingress Controller on Kubernetes
Daniele Venzano's avatar
Daniele Venzano committed
40
-----------------------------------------------------
qhoangxuan's avatar
qhoangxuan committed
41 42

Overview
Daniele Venzano's avatar
Daniele Venzano committed
43
^^^^^^^^
qhoangxuan's avatar
qhoangxuan committed
44
* We can access Zapps through a web proxy, so we do not need to open too many ports due to security reasons.
45 46 47
* This can be achieved when Zoe runs on Kubernetes by the support of an Ingress Controller.
* Automate the process of creating an ingress for a servive created by Zoe.
* Services which are exposed in Zapp can be accessed through the proxy url, which has the following format: ``http://servicename-executionid-deploymentname.proxy-path``
qhoangxuan's avatar
qhoangxuan committed
48 49

Requirements
Daniele Venzano's avatar
Daniele Venzano committed
50
^^^^^^^^^^^^
51 52 53 54 55
* A Kubernetes cluster which has:

  * Zoe
  * A (NGINX) ingress controller.
  * kubernetes-auto-ingress.
qhoangxuan's avatar
qhoangxuan committed
56 57

How it works
Daniele Venzano's avatar
Daniele Venzano committed
58
^^^^^^^^^^^^
qhoangxuan's avatar
qhoangxuan committed
59 60 61 62
1. Zoe configuration file:

 * ``--proxy-path``: the **ServerName** field in apache2 virtualhost configuration

63
2. (NGINX) ingress controller:
qhoangxuan's avatar
qhoangxuan committed
64

65 66
 * An Ingress is a collection of rules that allow inbound connections to reach the cluster services.
 * In order for the Ingress resource to work, the cluster must have an Ingress controller running. The Ingress controller will manage, configure the description in the Ingress resource to expose the associated services.
qhoangxuan's avatar
qhoangxuan committed
67

68
3. kubernetes-auto-ingress:
qhoangxuan's avatar
qhoangxuan committed
69

Daniele Venzano's avatar
Daniele Venzano committed
70
 * Currently, the process to submit an Ingress resource to the Ingress controller is manually done by cluster admins. kubernetes-auto-ingress automates this process. Every services have the labels "auto-ingress/enabled" is "enabled" will be automatically attached with the associated ingress resources.
qhoangxuan's avatar
qhoangxuan committed
71 72

References
Daniele Venzano's avatar
Daniele Venzano committed
73
^^^^^^^^^^
74 75 76
* Kubernetes Ingress: https://kubernetes.io/docs/concepts/services-networking/ingress/
* NGINX Ingress Controller: https://github.com/kubernetes/ingress/tree/master/controllers/nginx
* kubernetes-auto-ingress: https://github.com/hxquangnhat/kubernetes-auto-ingress