..
   SPDX-FileCopyrightText: © 2020 Open Networking Foundation <support@opennetworking.org>
   SPDX-License-Identifier: Apache-2.0

Deployment Guide
================


Provision Switches
------------------

We follow Open Network Install Environment(ONIE) way to install Open Network Linux (ONL) image to switch.
To work with the SD-Fabric environment, we have customized the ONL image to support related packages and dependencies.

Image source file can be found on ONF repository `opennetworkinglab/OpenNetworkLinux <https://github.com/opennetworkinglab/OpenNetworkLinux>`_.
You can also download pre-compiled artifacts from `Github Release page <https://github.com/opennetworkinglab/OpenNetworkLinux/releases>`_


.. note::
    If you're not familiar with ONIE/ONL environment, please check `Getting Started <https://github.com/opencomputeproject/OpenNetworkLinux/blob/master/docs/GettingStarted.md>`_ to
    see how to install the ONL image to an ONIE supported switch.

Below is an example about how to install the ONL image.

1. Prepare a server which is accessible by the switch and then download the
pre-compiled installer from the release page.

.. code-block::

   wget https://github.com/opennetworkinglab/OpenNetworkLinux/releases/download/v1.4.3/ONL-onf-ONLPv2_ONL-OS_2021-07-16.2159-5195444_AMD64_INSTALLED_INSTALLER
   python -m http.server 8080

2. Reboot the switch to enter ONIE installation mode

.. note::
    Please access the switch via BMC or serial console to keep connection during the installation.


.. code-block::

   onl-onie-boot-mode rescue; reboot

3. Install ONL installer

.. code-block::

   onie-nos-install http://$SERVER_IP:8080/ONL-onf-ONLPv2_ONL-OS_2021-07-16.2159-5195444_AMD64_INSTALLED_INSTALLER

4. Setup switch IP and hostname after the installation.


Kubernetes Environment
----------------------

Our `ONL <https://github.com/opennetworkinglab/OpenNetworkLinux>`_ version
includes all packages required by running the Kubernetes on top of it.
Once the Kubernetes is ready, the `Stratum <https://opennetworking.org/stratum/>`_ application will be deployed to the switch to manage it.

Unlike server, switch has less CPU and memory resources and we should avoid
deploying unnecessary workloads into switch.
Besides, the Stratum application should only be deployed to all switches.

To achieve the above goals, please apply the resources to your Kubernetes cluster.

1. Set up Label to all switch node, e.g ``node-role.kubernetes.io=switch``
2. Set up Taint with ``NoSchedule`` to all switch node, e.g ``node-role.kubernetes.io=switch:NoSchedule``
3. Properly configure the ``NodeSelector`` and ``Toleration`` when deploying Stratum via DaemonSet

Example of a five nodes Kubernetes cluster, two switches and three servers

.. code-block::

     ╰─$ kubectl get node -o custom-columns=NAME:.metadata.name,TAINT:.spec.taints
     NAME       TAINT
     compute1   <none>
     compute2   <none>
     compute3   <none>
     leaf1      [map[effect:NoSchedule key:node-role.kubernetes.io value:switch]]
     leaf2      [map[effect:NoSchedule key:node-role.kubernetes.io value:switch]]
     ╰─$ kubectl get nodes -lnode-role.kubernetes.io=switch                                                                                                             130 ↵
     NAME    STATUS   ROLES    AGE   VERSION
     leaf1   Ready    worker   27d   v1.18.8
     leaf2   Ready    worker   27d   v1.18.8


# TODO
Build Image
-----------

Fetch Images From Private Registry
----------------------------------

Container images can be download from ONF self-hosted container registry but you have to gain the access token first.

1. Login to `Aether Harbor Registry <https://registry.aetherproject.org/harbor/sign-in?redirect_url=%2Fharbor%2Fprojects>`_ using your ONF Crowd credential,
2. Select ``User Profile`` drop-down menu in the upper-right corner
3. Generate the CLI secret and it's the secret token you have to access the container registry via CLI tool.
4. Login to the container registry with your username and access token
   by ``docker login command`` to ensure you can access it.

.. code-block::

      ╰─$ docker login registry.aetherproject.org --username hwchiu                                                                                                          255 ↵
      Password:
      Login Succeeded


Please follow the `Kubernetes official document <https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/>`_ to see how to
download the image from the private registry with a valid credential


# TODO, wait for the umbrella chart
Install SD-Fabric
-----------------