Add content

README.md

@@ -5,3 +5,199 @@
 Common base for all commul work with docker and k8s. See the
 [template](https://gitlab.inf.unibz.it/commul/docker/template) for more
 information.
+
+## Init a Project with commons
+
+### Add the commons repo
+```bash
+git submodule add https://gitlab.inf.unibz.it/commul/docker/commons
+git submodule update --init --recursive
+```
+
+### Add minimal commons environment
+```bash
+ln -s commons/docker-helper
+```
+
+```
+cat << EOF > Chart.yaml
+apiVersion: v1
+name: <SOME-NAME>
+version: 0.1
+description: <SOME DESCRIPTION>
+home: https://gitlab.inf.unibz.it/commul/docker/<NAME>
+maintainers:
+  - name: Alexander König
+  - email: Alexander.Koenig@eurac.edu
+  - name: egon w. stemle
+  - email: egon.stemle@eurac.edu
+EOF
+```
+
+```
+cat << EOF > requirements.yaml
+dependencies:
+  - name: common
+    repository: file://./commons/external/kubernetes_charts/incubator/common/
+    version: 0.0.2
+  - name: commul_common
+    repository: file://./commons/helm-charts/commul_common/
+    version: 0.1.0
+    import-values:
+        - child: commul_common
+          parent: .
+EOF
+```
+
+### Initialise helm
+```bash
+helm dep build
+```
+
+### Create your templates
+```bash
+cat ./commons/helm-charts/webserver/values.yaml > values.yaml
+
+mkdir templates
+cp ./commons/helm-charts/webserver/templates/NOTES.txt templates/
+cp ./commons/helm-charts/webserver/templates/service.yaml templates/
+cp ./commons/helm-charts/webserver/templates/ingress.yaml templates/
+cp ./commons/helm-charts/webserver/templates/deployment.yaml templates/
+```
+
+### Create your Dockerfile and deploy
+```bash
+mkdir dockerfiles
+
+...
+
+./docker-helper build
+./docker-helper deploy
+```
+
+## Usage
+
+### Use Helm *without* Tiller to Deploy Charts
+
+#### Deploy, check, and delete a chart (Testing):
+```bash
+helm template -n <SOME-NAME> . | kubectl create -f -
+kubectl --namespace=kommul-dev get pod,svc,deployment,ingress --selector=release=<SOME-NAME>
+helm template -n <SOME-NAME> . | kubectl delete -f -
+```
+
+#### (UNTESTED) Deploy and Check a Chart (Production):
+```bash
+helm template -f values-prod.yaml -n test PATH_TO_WEBSERVER_CHART | kubectl create -f -
+kubectl --namespace=kommul get pod,svc,deployment,ingress --selector=release=test
+```
+
+
+## Prerequisites and Requirements
+
+### Docker
+
+`docker` needs to be locally [installed](https://docs.docker.com/install/) and
+running on your system (`docker ps`).
+
+### Kubernetes
+
+`kubectl` needs to be locally
+[installed](https://kubernetes.io/docs/tasks/tools/install-kubectl/) on your
+system, you need access to a k8s cluster and `kubectl` needs to be configured
+to access the cluster (`kubectl version`).
+
+### Helm *without* Tiller
+
+`helm` needs to be locally
+[installed](https://docs.helm.sh/using_helm/#installing-helm) on your system.
+
+### Helm *with* Tiller
+
+`helm` can also `deploy`, `rollback` and [more](https://daemonza.github.io/2017/02/20/using-helm-to-deploy-to-kubernetes/).
+For `helm` to be able to do this its server-side component `tiller` needs to be
+installed and configured.
+
+***NOTE***: the Helm/Tiller combo seems to be unreliable (likely, when running
+in individual namespaces - and not as a globally configured service...).
+Therefore, we currently only use the `helm template` functionality.
+
+#### Configure Helm and Install Tiller
+
+If your k8s cluster uses [RBAC
+Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
+you need to create a service account:
+```bash
+kubectl api-versions | grep rbac  # check if RBAC is enabled 
+kubectl create serviceaccount --namespace kommul-dev tiller
+```
+
+Then, you need to install tiller on the cluster:
+```bash
+# helm --tiller-namespace=kommul-dev init --upgrade
+# OR with RBAC
+helm --tiller-namespace=kommul-dev init --service-account=tiller --upgrade
+```
+
+To start over, i.e. to remove tiller use:
+```bash
+helm --tiller-namespace=kommul-dev reset --force
+```
+
+Afterwards, the following should work (we assume you are restricting the tools
+to individual k8s `--namespace`-s -- our running example will be `kommul-dev`).
+```bash
+K8S_NAMESPACE=kommul-dev
+kubectl config use-context $K8S_NAMESPACE
+export TILLER_NAMESPACE=$K8S_NAMESPACE  # alternative: --tiller-namespace=
+```
+
+```bash
+helm --tiller-namespace=kommul-dev version
+helm --tiller-namespace=kommul-dev list --all  # should give no error
+```
+
+#### Use Helm and Tiller to Deploy and Upgrade Charts
+
+Still, for (future) reference, here is how it should work.
+
+##### Deploy and Check a Chart
+Install the
+[webserver](https://gitlab.inf.unibz.it/commul/docker/commons/helm-charts/webserver/)
+chart with the release name `test` in the `kommul-dev`
+namespace:
+```bash
+helm --tiller-namespace=kommul-dev install -n test PATH_TO_WEBSERVER_CHART
+```
+
+Install the `prod`-uction version of the chart with the release name `test` in
+the `kommul` namespace:
+```bash
+helm --tiller-namespace=kommul install -f values-prod.yaml -n test PATH_TO_WEBSERVER_CHART
+```
+
+Check the deployment status on the cluster:
+```bash
+helm --tiller-namespace=kommul-dev status test
+```
+
+##### Delete a Deployment
+
+```bash
+helm --tiller-namespace=kommul-dev delete --purge test
+```
+
+##### Upgrade a Deployment
+```bash
+$ helm --tiller-namespace=kommul-dev upgrade test . \
+  --set image.repository=gitlab.inf.unibz.it:4567/commul/docker/commons/webserver \
+  --set image.tag=latest
+```
+
+## Miscellaneous
+```bash
+$ helm template . -f values-prod.yaml
+$ helm --tiller-namespace=kommul install . -n doc --dry-run --debug
+$ helm --tiller-namespace=kommul status test
+$ helm lint .
+```