.. SPDX-FileCopyrightText: 2024 - 2025 Univention GmbH
..
.. SPDX-License-Identifier: AGPL-3.0-only

.. _backup-restore-tool:

Backup tool: Velero
===================

This documentation uses :program:`Velero`,
because it takes care of the volume snapshots and conserves the resources
of your Nubus for Kubernetes deployment.
Snapshots ensure a consistent state within a persistent volume.

.. important::

     ⚠️ Univention Support **doesn't cover** Velero and using it. ⚠️

     This documentation uses Velero as an example to demonstrate the backup and restore procedure.

To install Velero follow the steps described in the `Velero documentation <https://velero.io/docs/latest/>`_.
You need to:

#. Install the Velero command-line client.
#. Install and configure the Velero server components.

.. important::

   Use the versions outlined in the Velero compatibility matrix,
   see :ref:`backup-restore-requirements`.

.. _backup-restore-tool-install:

Install Velero through CLI
--------------------------

The following steps describe how to install and configure the :program:`Velero` server components
using the Velero command-line client.
You can alternatively install the Velero server components using Helm,
but that's beyond the scope of this document.

Before you begin, make sure you meet the :ref:`backup-restore-requirements`.

#. Save the credentials for your object storage in a text file,
   for example :file:`credentials-velero`.
   The parameters vary depending on your storage provider.
   :numref:`backup-restore-tool-credentials-object-storage-listing`
   shows an example for MinIO S3-compatible storage.

   .. code-block:: ini
      :caption: Content of :file:`credentials-velero` with credentials to the MinIO object store provider
      :name: backup-restore-tool-credentials-object-storage-listing

      [default]
      aws_access_key_id = backup-for-nubus
      aws_secret_access_key = ohxiereiboh0vonohxohmeeF5gaeVohy

#. Open a shell on your local machine, where you installed the Velero command-line client
   to configure the environment as shown in :numref:`backup-restore-tool-setting-listing`.
   Use the :ref:`backup-restore-tool-observations` to help you decide on some settings.

   .. code-block:: console
      :caption: Settings for :program:`Velero`
      :name: backup-restore-tool-setting-listing

      $ export NAMESPACE_FOR_VELERO="your namespace for Velero"
      $ export VELERO_SECRET_FILE="./credentials-velero"
      $ export PROVIDER_FOR_VELERO="aws"
      $ export STORAGE_BUCKET_NAME="name to the bucket for backup"

      # Define the versions to use.
      # Verify the Velero compatibility matrix.
      $ export VERSION_VELERO="v1.13.2"
      $ export VERSION_PLUGIN_AWS="v1.9.2"
      $ export VERSION_PLUGIN_CSI="v0.7.1"

      # The URL to your S3-compatible storage API, including the port
      $ export S3_URL="http://minio.namespace-minio.svc:9000"

      #The URL to your S3-compatible storage API
      $ export S3_PUBLIC_URL="https://api.fqdn-s3-storage.example.com"

#. Install the Velero server components and pass the credentials and configuration for the plugins,
   as shown in :numref:`backup-restore-tool-install-listing`.

   .. code-block:: console
      :caption: Install :program:`Velero`
      :name: backup-restore-tool-install-listing

      $ velero install \
         --namespace "$NAMESPACE_FOR_VELERO" \
         --provider "$PROVIDER_FOR_VELERO" \
         --plugins=docker.io/velero/velero-plugin-for-aws:"$VERSION_PLUGIN_AWS",docker.io/velero/velero-plugin-for-csi:"$VERSION_PLUGIN_CSI" \
         --image docker.io/velero/velero:"$VERSION_VELERO" \
         --features=EnableCSI \
         --bucket "$STORAGE_BUCKET_NAME" \
         --secret-file "$VELERO_SECRET_FILE" \
         --velero-pod-mem-limit 1G \
         --backup-location-config \
             region=minio,s3ForcePathStyle="true",s3Url="$S3_URL",publicUrl="$S3_PUBLIC_URL"

.. seealso::

   `VMware Tanzu Helm Repository <https://vmware-tanzu.github.io/helm-charts/>`_
      for installation of Velero server components through Helm Charts.

   `Velero Docs - Customize Velero Install <https://velero.io/docs/latest/customize-installation/>`_
      for information about customizing the Velero installation.

.. _backup-restore-tool-observations:

Observations
------------

Memory limit for Velero server components
   The default memory limit for Velero in version ``1.13.2`` is 512 megabytes.
   During testing, the restore ended in a ``PartiallyFailed`` state with no detailed logging information,
   because the pod reached its memory limit and Kubernetes terminated the container.
   You can adjust the value to suit your needs.
   Starting with ``1G`` for one gigabyte gets you started.

Network configuration for storage provider
   If you run the object storage provider, such as MinIO, in a Kubernetes cluster,
   you need to make sure
   that your client with the Velero command-line client
   can reach the MinIO API at its default port ``9000``.
   If it can't,
   add a proper ingress configuration to your Kubernetes cluster
   that exposes the port for the MinIO API and issues a TLS certificate.

.. FYI: See the tests at the merge request for example of Ingress configuration for MinIO:
   https://git.knut.univention.de/univention/documentation/nubus-docs/-/merge_requests/47#note_368515