==================
Deploying Services
==================

To deploy a service to a Kubernetes cluster, the Github repository needs to
provide a Bash script that renders a Kubernetes manifest in YAML format to
standard out. This file must be located in the folder ``deploy/`` and named
``deploy.sh``.

``deploy.sh``
=============

The script should take the following environment variables into account when
generating the manifest:

**APP_REPO**
  | e.g. crate/cloud-api

  The repository of the service to deploy

**APP_VERSION**
  | e.g.  master | branch | commit hash | 0.7.2

  The service version to deploy

**K8S_ENV**
  | e.g. k8s-dev | k8s

  The Kubernetes environment (dev or prod)

**K8S_REGION**
  | e.g. bregenz | westeurope | aks1.westeurope | eks1.eu-west-1 | ...

  The name of the Kubernetes region

**K8S_PROVIDER**
  | e.g. a1 | azure | aws

  The Kubernetes provider

**K8S_CONTEXT**
  | $K8S_ENV.$K8S_REGION.$K8S_PROVIDER

  The Kubernetes context which should also reflect the name of the .yaml
  files with values for the templated variables.

Usage
-----

The script can then be invoked like so to deploy to a Kubernetes cluster:

.. code-block:: console

   $ export APP_REPO=crate/cloud-api
   $ export APP_VERSION=2020.11.3
   $ export K8S_ENV=k8s
   $ export K8S_REGION=bregenz
   $ export K8S_PROVIDER=a1
   $ export K8S_CONTEXT=$K8S_ENV.$K8S_REGION.$K8S_PROVIDER
   $ ./deploy.sh | kubectl --context $K8S_CONTEXT apply -f -

As a reference implementation of script, please look at the `crate/cloud-api`_
repository.

Jenkins
-------

The ``deploy.sh`` shell script is invoked by a `Jenkins job`_ configured with the
environment variables mentioned above.

Limitations
-----------

Since most deployments require some sort of credentials, the deploy scripts
usually require access to `Vault`_. However, access to Vault is restricted to
sysadmins. The Jenkins jobs can be invoked by any developer, though.

Helm
----

In order to use Helm to deploy a service, a Helm Chart must be add to the service
Github repo or into a dedicated GitHub repo.

Create a Chart
~~~~~~~~~~~~~~

.. code-block:: console

  helm create my-project

Remove/add the templates and the values.

Deploy from local folder
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console

  helm install my-service chart/path

Deploy from repo
~~~~~~~~~~~~~~~~

Add and configure the ``chart-releaser`` GitHub action in the GitHub repo in order to
host the charts. The ``index.html`` is served by using GitHub Pages.
Everytime the chart is modified (e.g. app version changed), a new release will be pushed.
See `Helm Chart Releaser`_ for further details.

Import the repo and install the chart:

.. code-block:: console

  helm repo add crate-operator https://crate.github.io/crate-operator
  helm install crate-operator crate-operator/crate-operator

Deployment in Jenkins
~~~~~~~~~~~~~~~~~~~~~

In order to be able to deploy each version of the code, we pull the GitHub repo and
install/upgrade the Chart from the local folder.
The values can be overwritten by applying one or many values file in order
to have the good environment values with ``-f`` or with ``--set`` to change just one
value.

.. code-block:: console

  helm upgrade crate-operator deploy/charts/crate-operator \
    -f crate_cloud/crate-operator/helm-values/common.yaml \
    -f crate_cloud/crate-operator/helm-values/\${K8S_CONTEXT}.yaml \
    --install \
    --atomic \
    --namespace "cloud-app" \
    --set image.tag="\${APP_VERSION}" \
    --set crate-operator-crds.enabled=false \
    --kube-context "\${K8S_CONTEXT}"

.. _crate/cloud-api: https://github.com/crate/cloud-api/tree/master/deploy
.. _Jenkins job: https://jenkins.crate.io/job/devops/job/deploy/
.. _Vault: https://vault.bregenz.a1.cr8.net:8200/
.. _Helm Chart Releaser: https://github.com/marketplace/actions/helm-chart-releaser