Add example deployment for k8s, update docs (#162)

deploy/docker/README.md

@@ -3,8 +3,8 @@ This directory contains examples for [docker-compose][docker-compose] based depl
 of Synse Server (v2.0+) with the containerized Emulator Plugin.
 
 ## Deployments
-As a general note - the Emulator Plugin does not need to be containerized. In
-fact, it is built into non-slim Synse Server 2.0 images so that it can run
+As a general note - the Emulator Plugin does not need to be containerized separately.
+In fact, it is built into non-slim Synse Server 2.0+ images so that it can run
 alongside Synse Server, providing an easy way to get started/demo/play with it.
 
 In this case, we use a containerized version of the same emulator in order to

deploy/k8s/README.md

@@ -0,0 +1,109 @@
+# Deploying on Kubernetes
+This directory contains an example deployment of Synse Server with a containerized
+Emulator Plugin for [Kubernetes][kubernetes].
+
+## Deployments
+As a general note - the Emulator Plugin does not need to be containerized separately.
+In fact, it is built into non-slim Synse Server 2.0+ images so that it can run
+alongside Synse Server, providing an easy way to get started/demo/play with it.
+
+In this case, we use a containerized version of the same emulator in order to
+give us a plugin that is not dependent on any platform or hardware. This makes 
+the example here a good place to get started. Additionally, we use a slim version
+of Synse Server as to prove that the data is coming from the external emulator only.
+
+The example deployment here sets up a simple Synse Server instance and an instance
+of the Plugin Emulator within the same pod. Both Synse Server and the plugin are
+configured to communicate via gRPC over TCP. Currently, the [plugin SDK][synse-sdk]
+(via the [internal gRPC API][synse-grpc]) supports communication via TCP and UNIX
+socket, but for Kubernetes deployments, it is highly preferred to use TCP over UNIX
+sockets.
+
+## Setup
+For this example you will need:
+- a basic understanding of Kubernetes
+- an operational Kubernetes cluster
+- access to the Kubernetes cluster
+- [`kubectl`][kubectl], configured to talk to your cluster
+
+It may also be useful to get the [Synse CLI][synse-cli] to interact with Synse Server.
+
+It is also recommended that you have a basic understanding of how Synse Server
+works, how Synse Plugins work, and how the two interact. This is not required
+to get the deployment working, but is useful in understanding the deployment configuration.
+For more, see:
+- [Synse Server User Guide][synse-user-guide]
+- [Synse SDK Documentation][synse-sdk-docs]
+
+
+## Usage
+Deploying to your cluster should be straightforward using standard `kubectl` commands.
+
+With this repo checked out, you can do this locally, e.g.
+```
+kubectl apply -f synse-with-emulator.yml
+```
+
+Or, you can just use the URL to the YAML config
+```
+kubectl apply -f https://raw.githubusercontent.com/vapor-ware/synse-server/master/deploy/k8s/synse-with-emulator.yml
+```
+
+Kubernetes should now do all the heavy lifting!
+
+
+Once one of the deployments is running, you can test out that Synse Server is reachable.
+First you will need to get the IP of pod. From within the cluster:
+```console
+$ kubectl get pods -o wide
+NAME                            READY     STATUS    RESTARTS   AGE       IP             NODE
+synse-server-7785ffdd54-dtn98   2/2       Running   0          44s       10.244.0.239   vec8
+```
+
+Here, our pod IP is `10.244.0.239`.
+
+
+Using that IP, we can test that Synse Server is reachable and OK.
+```
+curl <pod id>:5000/synse/test
+```
+
+If successful, you are ready to go. Next, perform a scan to see everything that is available
+via the plugin:
+```
+curl <pod ip>:5000/synse/2.0/scan
+```
+
+This should give back a set of devices - in particular:
+- 2 LED devices
+- 2 temperature devices
+
+If you look at the log output of the Emulator Plugin , you should see that these results
+match up with what that plugin had registered on startup.
+
+You can also do the above with the Synse CLI. First you'll need to add the IP as a host,
+and set that as the active host.
+```
+synse hosts add example 10.244.0.239
+synse hosts change example
+```
+
+Then, to test the status:
+```
+synse server status
+```
+
+And to get the scan information:
+```
+synse server scan
+```
+
+See the help information for the Synse CLI for more usage info.
+
+[kubernetes]: https://kubernetes.io/
+[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
+[synse-cli]: https://github.com/vapor-ware/synse-cli
+[synse-sdk]: https://github.com/vapor-ware/synse-sdk
+[synse-grpc]: https://github.com/vapor-ware/synse-server-grpc
+[synse-user-guide]: http://synse-server.readthedocs.io/en/latest/
+[synse-sdk-docs]: http://synse-sdk.readthedocs.io/en/latest/

deploy/k8s/synse-with-emulator.yml

@@ -0,0 +1,136 @@
+# This file is a simple example of a Kubernetes deployment with Synse Server
+# and a single plugin, the emulator plugin. It is meant for demonstration
+# purposes, and can be used as an example for creating your own deployments
+# with Synse Server.
+
+
+# Configuration for the Emulator Plugin
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: emulator-plugin-config
+  labels:
+    name: emulator-plugin-config
+data:
+  config.yml: |
+    version: 1.0
+    name: emulator
+    debug: true
+    network:
+      type: tcp
+      address: "0.0.0.0:5001"
+    settings:
+      mode: parallel
+      read:
+        interval: 1s
+      write:
+        interval: 1s
+---
+# A simple device configuration for the emulator plugin. This
+# will make 2 temperature devices and 2 LED devices available
+# to Synse Server.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: emulator-device-config
+  labels:
+    name: emulator-device-config
+data:
+  devices.yml: |
+    version: 1.0
+    locations:
+      r1vec:
+        rack:
+          from_env: NODE_NAME
+        board: vec
+    devices:
+      - type: temperature
+        model: emul8-temp
+        instances:
+          - id: "1"
+            location: r1vec
+            info: Synse Temperature Sensor 1
+          - id: "2"
+            location: r1vec
+            info: Synse Temperature Sensor 2
+      - type: led
+        model: emul8-led
+        instances:
+          - id: "1"
+            location: r1vec
+            info: Synse LED
+          - id: "2"
+            location: r1vec
+            info: Synse backup LED
+---
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: synse-server
+  labels:
+    app: synse-server
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: synse-server
+  template:
+    metadata:
+      labels:
+        app: synse-server
+    spec:
+      volumes:
+        - name: emulator-plugin-config
+          configMap:
+            name: emulator-plugin-config
+        - name: emulator-device-config
+          configMap:
+            name: emulator-device-config
+      containers:
+        - name: synse-server
+          image: vaporio/synse-server:latest-slim
+          ports:
+            - name: http
+              containerPort: 5000
+          env:
+            # Enable debug logging via ENV config
+            - name: SYNSE_LOGGING
+              value: debug
+            # Register the Emulator Plugin via ENV config
+            - name: SYNSE_PLUGIN_TCP_EMULATOR
+              value: localhost:5001
+          resources:
+            requests:
+              cpu: 25m
+              memory: 100Mi
+        - name: emulator-plugin
+          image: vaporio/emulator-plugin:edge
+          ports:
+            - name: http
+              containerPort: 5001
+          env:
+            # Set pass the NODE_NAME to the container - this will be used
+            # as the rack id (see plugin device config)
+            - name: NODE_NAME
+              valueFrom:
+                fieldRef:
+                  fieldPath: spec.nodeName
+            - name: PLUGIN_DEVICE_PATH
+              value: /tmp/device/config
+            - name: PLUGIN_CONFIG
+              value: /tmp/plugin
+          resources:
+            requests:
+              cpu: 25m
+              memory: 100Mi
+          volumeMounts:
+            # Mount in the emulator plugin configuration to a non-default location.
+            # This path is registered with the plugin via the PLUGIN_CONFIG enviroment
+            # variable.
+            - name: emulator-plugin-config
+              mountPath: /tmp/plugin
+            # Mount in the emulator plugin device config to a non-default location.
+            # This path is registered with the plugin via the PLUGIN_DEVICE_PATH
+            # environment variable.
+            - name: emulator-device-config
+              mountPath: /tmp/device/config

docs/source/user/deployment.rst

@@ -10,9 +10,9 @@ with Synse Server and plugins.
 Deploying with Docker Compose
 -----------------------------
 For a complete set of examples for deploying with ``docker compose``, see the
-emulator example deployments in the ``deploy`` directory of the Synse Server source.
-This section goes into detail on how to deploy Synse Server with an externally
-running emulator plugin configured for TCP communication.
+emulator example deployments in the `deploy/docker directory <https://github.com/vapor-ware/synse-server/tree/master/deploy/docker>`_
+of the Synse Server source. This section goes into detail on how to deploy Synse Server
+with an externally running emulator plugin configured for TCP communication.
 
 For Synse Server, all that we really need to do is specify the plugin in the
 container's configuration. As you may recall from the :ref:`configuration` section,
@@ -239,4 +239,5 @@ To bring the deployment down,
 
 Deploying with Kubernetes
 -------------------------
-Coming soon
+A simple example deployment of Synse Server and the containerized Plugin Emulator can
+be found in the project source's `deploy/k8s directory <https://github.com/vapor-ware/synse-server/tree/master/deploy/k8s>`_.