From 97810e1ee09e42f474e6f8176e4f34d737cd5144 Mon Sep 17 00:00:00 2001
From: Sergiusz Bazanski <q3k@q3k.org>
Date: Mon, 27 Aug 2018 21:00:46 +0100
Subject: [PATCH] Add README.md

---
 README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..59b8335f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+Old Shitty Arista eAPI/Capi <-> gRPC proxy
+==========================================
+
+Our Arista 7148S does not support gRPC/OpenConfig, so we have to make our own damn gRPC proxy.
+
+The schema is supposed to be 1:1 mapped to the JSON-RPC EAPI. This is just a dumb proxy.
+
+PKI Introduction
+----------------
+
+This project is a testing ground for the HSCloud PKI setup. Long story short,
+all gRPC is mutually authenticated via TLS (server & client certs).
+
+All certs for mutual auth have the following CN/SAN format:
+
+   <job>.<principal>.<realm>
+
+For example, if principal maps into a 'group' and job into a 'user':
+
+   arista-proxy-dcr01u23.prod.c.example.com
+
+   job = arista-proxy-dcr01u23
+   principal = cluster-management-prod
+   realm = c.example.com
+
+The Realm is a DNS name that is global to all jobs that need mutual authentication.
+
+The Principal is any name that carries significance for logical grouping of jobs.
+It can, but doesn't need to, group jobs by similar permissions.
+
+The Job is any name that identifies uniquely (within the principal) a security
+endpoint that describes a single security policy for a gRPC endpoint.
+
+The entire CN should be DNS resolvable into an IP address that would respond to
+gRPC requests on port 42000 (with a server TLS certificate that represents this CN) if the
+job represents a service.
+
+This maps nicely to the Kubernetes Cluster DNS format if you set `realm` to `svc.cluster.local`.
+Then, `principal` maps to a Kubernetes namespace, and `job` maps into a Kubernetes service.
+
+    arista-proxy-dcr01u23.arista-prod.svc.cluster.local
+
+    job/service = arista-proxy-dcr01u23
+    principal/namespace = arista-prod
+    realm = svc.cluster.local
+
+ACLs based on job/principal are yet to be implemented :).
+
+PKI Certs for Development
+-------------------------
+
+In production, those certs will be automatigacally provided for you by
+automation. In development, you'll have to do the following:
+
+    cd pki
+    ./gen.sh
+
+This will generate:
+ - `pki/ca.pem` - CA certificate
+ - `pki/client{,-key}.pem` - certificate and key for `developer.humans.svc.cluster.local`
+ - `pki/service{,-key}.pem` - certificate and key for `test.arista-proxy.svc.cluster.local`
+
+You will have to setup an /etc/hosts alias to make `test.arista-proxy.svc.cluster.local` resolve to your machine.
+
+    # cat /etc/hosts
+    ...
+    127.0.0.1 test.arista-proxy.svc.cluster.local
+    ...
+
+You can then start `arista-proxy` with default flags and talk to it via gRPC:
+
+    ./arista-proxy
+
+    alias grpc-dev="grpc -cacert $(pwd)/pki/ca.pem -key $(pwd)/pki/client-key.pem -cert $(pwd)/pki/client.pem"
+    grpc-dev test.arista-proxy.svc.cluster.local:42000 proto.AristaProxy.ShowVersion
+