Merge pull request #289 from Accenture/288-helm-v3

288 - Add helm v3 template and update deployment instructions

Author: Knappek

.gitignore

@@ -39,3 +39,6 @@ erl_crash.dump
 /.elixir_ls/
 *~
 *.orig
+
+# asdf 
+.tool-versions

CHANGELOG.md

@@ -14,13 +14,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added basic distributed tracing support in [W3C Trace Context specification](https://www.w3.org/TR/trace-context/) with Jaeger and Openzipkin exporters. RIG opens a span at the API Gateway and emits trace context in Cloud Events following the [distributed tracing spec](https://github.com/cloudevents/spec/blob/v1.0/extensions/distributed-tracing.md). [#281](https://github.com/Accenture/reactive-interaction-gateway/issues/281)
 - Added possibility to set response code for `response_from` messages in reverse proxy (`kafka` and `http_async`). [#321](https://github.com/Accenture/reactive-interaction-gateway/pull/321)
 - Added new version - `v3` - for internal endpoints to support response code in the `/responses` endpoint
+- Added Helm v3 template to the `deployment` folder [#288](https://github.com/Accenture/reactive-interaction-gateway/issues/288)
 
 ### Changed
 
 - Incorporated [cloudevents-ex](https://github.com/kevinbader/cloudevents-ex) to handle binary and structured modes for [Kafka protocol binding](https://github.com/cloudevents/spec/blob/v1.0/kafka-protocol-binding.md) in a proper way. This introduces some **breaking changes**:
   - Binary mode is now using `ce_` prefix for CloudEvents context attribute headers, before it was `ce-` - done according to the [Kafka protocol binding](https://github.com/cloudevents/spec/blob/v1.0/kafka-protocol-binding.md)
 - Change above affects also `"response_from": "kafka"` proxy functionality. RIG will forward to clients only Kafka body, no headers. This means, when using binary mode, clients receive only the data part, no CloudEvents context attributes.
 - Changed `response_from` handler to expect a message in binary format, **NOT** a cloud event (`kafka` and `http_async`). [#321](https://github.com/Accenture/reactive-interaction-gateway/pull/321)
+- Updated Helm v2 template, kubectl yaml file and instructions in the `deployment` folder [#288](https://github.com/Accenture/reactive-interaction-gateway/issues/288)
 
 ### Fixed
 

deployment/README.md

@@ -1,30 +1,95 @@
-# Distributed deployment
+# Running RIG on Kubernetes
 
-Reactive Interaction Gateway (RIG) uses [Peerage library](https://github.com/mrluc/peerage) to do discovery in distributed mode (production Distillery release).
+## Kubectl
 
-**Note:** If you don't care about distributed mode and don't want to do discovery, follow just `General configuration` section and ignore rest of the text.
+```bash
+kubectl apply -f kubectl/rig.yaml
+```
 
-## Configuration
+## Helm
+
+The Helm Charts are stored in [./helm2](./helm2) and [./helm3](./helm3) directory, which are essentially the same but only use a different `apiVersion` in the `Chart.yaml`.
+
+### Version 2
+
+```bash
+cd helm2
+# dry run to verify that everything is ok
+helm install --name=rig reactive-interaction-gateway --dry-run
+# install
+helm install --name=rig reactive-interaction-gateway
+```
+
+### Version 3
+
+```bash
+cd helm3
+# dry run to verify that everything is ok
+helm install rig reactive-interaction-gateway --dry-run
+# install
+helm install rig reactive-interaction-gateway
+```
+
+## Communication
+
+Both `kubectl` and `helm` deploy bunch of Kubernetes resources:
+
+- deployment - manages pod(s)
+- service - provides the main communication point for other applications
+- headless service - takes care of DNS discovery used internally
 
-### General configuration
+To allow external communication (outside of your cluster) do:
 
-1. Node host - Every node in cluster needs to be discoverable by other nodes. For that Elixir/Erlang uses so called `long name` or `short name`. We are using `long name` which is formed in the following way `app_name@node_host`. `app_name` is in our case set to `rig`, but `node_host` is taken from environment variable `NODE_HOST`. This can be either IP or container alias or whatever that is routable in network by other nodes.
+```bash
+# both helm versions
+helm upgrade --set service.type=LoadBalancer rig reactive-interaction-gateway
+# for kubectl update kubectl/rig.yaml to use a service of type LoadBalancer instead of ClusterIP
+```
 
-1. Node cookie - Nodes in Erlang cluster use cookies as a form of authorization/authentication between them. Only nodes with the same cookie can communicate together. It should be ideally some generated hash, set it to `NODE_COOKIE` environment variable.
+## Scaling
 
-### DNS discovery
+Scale the deployment and create multiple pods
 
-RIG currently supports distributed deployment via DNS discovery. To make it work, you need to set two environment variables:
+```bash
+helm upgrade --set service.type=LoadBalancer --set replicaCount=<replicas> rig reactive-interaction-gateway
+# or
+kubectl scale deployment/<deployment_name> --replicas <replicas>
+```
 
-1. Discovery type - Currently RIG supports only DNS discovery. To use DNS, set `DISCOVERY_TYPE` to `dns`.
+You can also inspect the logs of the pods with `kubectl logs <pod_name>` to see how they automatically re-balance Kafka consumers (if you are using Kafka) and adapt Proxy APIs from other nodes.
 
-1. DNS name (address) - Address where peerage will do discovery for Node host addresses. Value is taken from environment variable `DNS_NAME`.
+## Configuration
+
+### Node host
+
+Every node in cluster needs to be discoverable by other nodes. For that Elixir/Erlang uses so called `long name` or `short name`. We are using `long name` which is formed in the following way `app_name@node_host`. `app_name` is in our case set to `rig` and `node_host` is taken from environment variable `NODE_HOST`. This can be either IP or container alias or whatever that is routable in network by other nodes.
+
+We are using the pod IP with:
+
+```yaml
+- name: NODE_HOST
+  valueFrom:
+    fieldRef:
+      fieldPath: status.podIP
+```
 
-DNS discovery is executed every 5 seconds.
+### Node cookie
+
+Nodes in Erlang cluster use cookies as a form of authorization/authentication between them. Only nodes with the same cookie can communicate together. Ideally, it is some generated hash, that's why we recommend adapting `NODE_COOKIE` environment variable in the `values.yaml`.
 
 ### Additional configuration
 
-When running in distributed mode, additional variables may be passed to the deployment in order to run the proper configuration.
-Changes to these variables are required in most production circumstances.
+You can configure bunch of environment variables, please check the [Operator's Guide](https://accenture.github.io/reactive-interaction-gateway/docs/rig-ops-guide.html).
+
+## Cleanup
+
+```bash
+# kubectl
+kubectl delete -f kubectl/rig.yaml
+
+# Helm v3
+helm uninstall rig
 
-For more information on configuration variables, please view the [Operator's Guide to the RIG](https://accenture.github.io/reactive-interaction-gateway/docs/rig-ops-guide.html)
+# Helm v2
+helm delete --purge rig
+```