From 6f99c52b8b5c1fa4d3fceacff0f5dd363a4923a1 Mon Sep 17 00:00:00 2001 From: Christine Dodrill Date: Sat, 30 Nov 2019 16:09:13 -0500 Subject: [PATCH] doc/spec: update --- doc/spec.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 101 insertions(+), 2 deletions(-) diff --git a/doc/spec.md b/doc/spec.md index 0420b1c..6de191b 100644 --- a/doc/spec.md +++ b/doc/spec.md @@ -13,5 +13,104 @@ the complexity of the setup increases. We need a better option. -Iconia is a service gateway designed to help alleviate these problems while -maintaining the +Iconia is a service gateway that integrates into [Caddy][caddy] to allow for a +better experience operating complicated applications at scale. The ultimate +goal of Iconia is to allow services to not require a direct TCP line-of-fire +from the load balancer to the backend services. Instead the Iconia agent would +connect to the load balancer and redirect traffic to the backend, much like it +would in service meshes like Envoy or Istio. + +### Name Origin + +The name of Iconia is a reference to the [Iconian gateway][gateway] from the +Star Trek franchise. It is a gateway that allows for instant travel to distant +points in the galaxy in ways that bypass shields and other forms of security. +The name is used here because Iconia is a gateway to distant services that +bypasses NAT and other ways that ports get blocked. + +## Components + +Iconia is made up of several components: + +- [Caddy][caddy] as the ingress/TLS terminating component +- The Iconia agent running alongside the application being exposed to the world +- The application being exposed via Iconia + +### Caddy Plugin + +The Caddy plugin for Iconia MUST perform the following operations: + +- Gather metrics about the performance of each backend: + - Roundtrip time + - Time to first byte + - Number of connections + - Time it takes to do healthchecks + - A healthcheck metric defined by the backend application +- Gather metrics: + - Number of connected backends + - Number of authentication failures +- Have some method to intelligently select backends based on the following + criteria: + - Load of the backend service instance in question + - Client remote IP address and port number + - Backend health status (IE: it MUST NOT route to backends that are marked + as unhealthy) +- Expose a protocol or method for backend services to connect to the + concentrator + - Evaluate [smux][smux], [SSH][ssh] and [Quic][quic] + - Ensure that only authorized agents are allowed to register as backends +- Expose an API for controlling Iconia operations + - List active backends + - See details about a given backend by connection ID + - Kill an arbitrary backend by connection ID +- Log messages to the standard Caddy logging sink +- Route requests and responses to and from the discovered backend + efficiently + +The Caddy plugin for Iconia MUST support allowing backends for multiple hosts +to connect via the same TCP/UDP port. + +### Iconia Agent + +The Iconia agent MUST perform the following operations: + +- Discover/gather configuration information from the environment and filesystem +- Connect to the gateway server in a durable and fault-tolerant manner +- Authenticate to the gateway server +- Listen for incoming TCP sessions from the gateway server and route them to the + backend service +- Utilize the [PROXY protocol][proxyprotocol] to ensure that the backend service + has accurate information about client IP addresses + +### Backend Service + +Backend services for Iconia MUST have the following properties: + +- Understand the [PROXY protocol][proxyprotocol] to ensure that the backend + service has accurate information about client IP addresses +- Expose a healthcheck route: + - On the HTTP host `iconia-healthcheck` + - With the path `/health` + - That MAY return `200` if everything is healthy with the body `OK` + - And also MAY return `500` if everything is NOT healthy with the body + containing a site-defined error message explaining what the issue is + - This healthcheck MAY include the response header `X-Iconia-Load` to send the + gateway a site-defined load metric to help the gateway choose the backend + with the least load +- Accepts connections over TCP to a known port + +## Caveats + +This will undoubtedly add a slight amount of latency to standard HTTP operations. +Applications that are latency sensitive should probably avoid using this tool in +favor of traditional exposure methods. + +The Go HTTP/2 stack doesn't currently support connection hijacking. This will be +needed in order to have the most efficient routing possible. + +[caddy]: https://caddyserver.com +[gateway]: https://memory-alpha.fandom.com/wiki/Iconian_gateway +[smux]: https://github.com/xtaci/smux +[ssh]: https://godoc.org/golang.org/x/crypto/ssh +[quic]: https://godoc.org/github.com/lucas-clemente/quic-go +[proxyprotocol]: https://github.com/joyent/haproxy-1.5/blob/master/doc/proxy-protocol.txt