=================================
Installation on Kubernetes (Helm)
=================================

This guide describes how to deploy ``QKDLite`` onto a Kubernetes
cluster using Helm.

Prerequisites
=============

**Cluster**

* A reachable Kubernetes cluster, with ``kubectl`` configured against the
  target context.
* One of the following mechanisms for external traffic:

  * A Gateway API controller with a ``GatewayClass`` installed, including the
    ``TCPRoute``/``TLSRoute`` CRDs
  * A ``LoadBalancer`` service implementation (e.g. MetalLB, ServiceLB)

**Tooling**

* Helm 3.8 or later

**Security material**

* TLS certificates: Root CA certificate, server certificate, and server key
  (see :doc:`tool_pqCAlite` for pqCAlite)
* The passphrase protecting the TLS server key

**Artifacts and access**

* Credentials for the QKDLite registry (``qkdlite.azurecr.io``); for
  air-gapped environments, see :doc:`installation_kubernetes_airgap`
* The QKDLite installer package


Quick Installation
====================

From script
------------------

#. Execute the oci tooling script

   .. code-block:: console
      :caption: console on QKDLite main node

      $ cd QKDLite_helm
      $ ./install_oci_tooling.sh


#. Execute the installer script

   .. code-block:: console
      :caption: console on QKDLite main node

      $ cd QKDLite_helm
      $ ./install_QKDLite_helm.sh


#. Enter the namespace where QKDLite will be installed, and the release name of QKDLite

   .. code-block:: console
      :caption: console on QKDLite main node

      Setting up QKDLite environment
      Enter Kubernetes namespace [default]:
      Enter Helm Release Name [default]:

#. Enter registry URL and Chart Url. The chart can either be a direct remote URL or a local file path.
   To use the remote registry press enter to continue.

   .. code-block:: console
      :caption: console on QKDLite main node

      Container registry to pull images from [qkdlite.azurecr.io]:
      Enter Helm Chart Location [oci://qkdlite.azurecr.io/charts/qkdlite]:

#. Enter the file path of the certificates and the passphrase

   .. code-block:: console
      :caption: console on QKDLite main node

      Setting up QKDLite TLS certs...
      Path to ca.crt [../pqCAlite/certs/CA.crt]:
      Path to tls.crt [../pqCAlite/certs/2607_test_server_test.crt]:
      Path to tls.key [../pqCAlite/private/2607_test_server_test.key]:
      TLS Key passphrase [optional, press Enter to skip]:


   .. note::

      Ensure that the tls.crt and tls.key chosen have a server prefix


#. Enter the username and password of registry to retrieve images and helm package.

   .. code-block:: console
      :caption: console on QKDLite main node

      Setting up QKDLite registry secrets...
      Does registry (qkdlite.azurecr.io) require authentication? [y/N]: y
      Registry User: user
      Registry Password:
      Registry Password (confirm):
      Login Succeeded


#. Enter the main and remote node names.

   .. note::
      The Security Application Entity (SAE) name is required for the proper labelling
      of quantum keys to be provided via the ETSI server. For an exmaple, we can use "SAE_A"
      for QKDLITE_SAE_A and "SAE_B" for QKDLITE_SAE_B.

      If you are on QKDLITE_SAE_A, press Enter to use the defaults for "SAE_A" for main node
      and "SAE_B" for remote node. If you are on QKDLITE_SAE_B, enter "SAE_B" for main node
      and "SAE_A" for remote node.

   .. code-block:: console
      :caption: console on QKDLite main node

      Generating values file for QKDLite...
      Name of local node (can be changed later) [SAE_A]:
      Name of remote node (can be changed later) [SAE_B]:
      Remote node IP address (can be changed later) [127.0.1.0]:


#. Enter the Transport Key Data. Press enter to autogenerate a new value, or type to
   add in a existing Transport Key. The Transport Key Data must be the same for all paired
   nodes, otherwise key replication will fail.

   #. Auto Generation

      .. code-block:: console
         :caption: console on QKDLite main node

         Setting up secrets for QKDLite...
         Transport Key Data [press Enter to autogenerate, or type to set]:
            ✓ Autogenerated

   #. Manual

      .. code-block:: console
         :caption: console on QKDLite main node

         Setting up secrets for QKDLite...
         Transport Key Data [press Enter to autogenerate, or type to set]:
         Transport Key Data (confirm):


#. Enter the Bootstrap Key Data if bootstrap feature is needed. Press enter to
   autogenerate a new value, or type to add in a existing bootstrap key. The Bootstrap
   Key Data must be the same for all paired nodes, otherwise key replication will fail.

   #. Auto Generation

      .. code-block:: console
         :caption: console on QKDLite main node

         Bootstrap needed? [y/N]: y
         Bootstrap Key Data [press Enter to autogenerate, or type to set]:
            ✓ Autogenerated

   #. Manual

      .. code-block:: console
         :caption: console on QKDLite main node

         Bootstrap needed? [y/N]: y
         Bootstrap Key Data [press Enter to autogenerate, or type to set]:
         Bootstrap Key Data (confirm):


#. The script will proceed to install QKDLite.


   .. code-block:: console
      :caption: console on QKDLite main node

      Installing QKDLite with Helm...
      Release "default" does not exist. Installing it now.
      Pulled: qkdlite.azurecr.io/helm/qkdlite:0.1.4
      Digest: sha256:84487e635790f1a4690758f4a86dfeb1b3265175dd0ef999d7ef4a510aca2abf
      NAME: default
      LAST DEPLOYED: Tue Jan 30 xx:xx:xx 2025
      NAMESPACE: default
      STATUS: deployed
      REVISION: 1
      TEST SUITE: None


Verifying the Installation
==========================

.. code-block:: console

   $ kubectl get pods -n <namespace>

Confirm that all pods reach the ``Running`` state and that readiness probes
pass before proceeding.


Upgrading
=========

Apply changes to an existing release by editing ``values.yaml`` and running an
upgrade.

   .. code-block:: console

      $ ./install_QKDLite_helm.sh