.. include:: global.rst.inc
.. _container:

Containerized Benji
===================

Images
------

benji
~~~~~

This image is based on CentOS 7 but uses the newer Python versions provided by IUS. It includes Benji and its
dependencies. Ceph support is also present.

The Benji configuration should be put into ``/etc/benji/benji.yaml``. Either by inheriting from this image and
overwriting it or by mounting it directly into the container. By default a minimal test configuration is provided
by the image.

The default Docker entry point is just ``/bin/bash``.

One use case for this image is for testing Benji::

    docker run --interactive --tty --rm elementalnet/benji

After that you can directly proceed with step 1 of the instructions
in section :ref:`quickstart`.

The second use case would be to get some real work done without directly installing Benji on the host. A series of
scripts to facilitate the calling of Benji are provided under ``/scripts`` inside the container. They can also be found
in the ``scripts`` directory of the source distribution. For an example of how to use these scripts please see
``images/benji-k8s/scripts/benji-backup-pvc``.

benji-k8s
~~~~~~~~~

This image is directly derived from the ``benji`` image above. It includes a framework to do periodic backups of
Kubernetes  persistent volumes backed by Ceph RBD. To access Kubernetes ``kubectl`` is used.

When the image is started a regular ``crond`` is launched. All periodic actions can be configured via
``/benji/etc/crontab``. By default this file is empty but here is one possible example::

    PROM_PUSH_GATEWAY=:9091
    BENJI_INSTANCE:-benji-k8s
    00  * * * * root benji-backup-pvc --all-namespaces -l 'release in (prod)'
    03  * * * * root benji-backup-pvc --namespace staging
    00 04 * * * root benji-command enforce latest3,hours24,days30,months3 'labels["benji-backup.me/instance"] == "benji-k8s"'
    00 05 * * * root benji-command cleanup
    30 05 * * * root benji-versions-status
    00 06 * * * root benji-command batch-deep-scrub --version-percentage 10 --block-percentage 33 'labels["benji-backup.me/instance"] == "benji-k8s"'

When the environment variables ``PROM_PUSH_GATEWAY`` and ``BENJI_INSTANCE`` are not set, they default to the above
listed values.

The backup script ``benji-backup-pvc`` first searches for ``PersistemtVolumeClaims`` matching the selector supplied on
the command line. Direct backups of ``PersistentVolumes`` are currently not supported by this script.

.. TIP:: See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
    for possible ways to construct your selector.

``benji-command enforce`` should be called regularly to expire old backup versions. Also ``benji-command cleanup`` needs
to be executed once in a while to actually remove blocks that are no longer used from the storages.

At the end of each command related `Prometheus <https://prometheus.io/>`_ metrics are pushed to the configured
`pushgateway <https://github.com/prometheus/pushgateway>`_. If ``PROM_PUSH_GATEWAY`` is not set, this step is skipped.

The backup script uses Ceph's and Benji's differential backup features if possible. Normally only the initial backup
is a full backup. RBD snapshots names are generated with a prefix of ``b-``.

Helm Charts
-----------

Helm charts are the preferred way to deploy the ``benji-k8s`` image.

benji-k8s
~~~~~~~~~

Benji includes a Helm chart to use the Docker image of the same name. It consists
of a Deployment and supporting resources and assumes that you have RBAC in place.
The deployment is composed a two containers: One running the benji-k8s Docker image
and another one running a `Prometheus <https://prometheus.io/>`_
`pushgateway <https://github.com/prometheus/pushgateway>`_. These can be scraped
by a Prometheus server and the Pod generated by the Deployment has annotations
so that it can be detected automatically::

      annotations:
        prometheus.io/port: "{{ .Values.pushgateway.port }}"
        prometheus.io/scrape: "true"

.. NOTE:: The deployed resources create a service account which has the right to *get*,
    *list* and *watch* all PersistentVolume, PersistentVolumeClaim, Storageclasses and Pod resources in all
    namespaces. Additionally it is able to *create* Events.
