Refactor deployment guide
Keep preparation work here and move Helm chart installation instruction to Helm README
Change-Id: I2d4ad25d2f187bb9369c60ffa725e661dae1f63f
diff --git a/configuration/network.rst b/configuration/network.rst
index 14efe64..dbe6426 100644
--- a/configuration/network.rst
+++ b/configuration/network.rst
@@ -1,3 +1,5 @@
+.. _onos_network_config:
+
Network Configuration
=====================
SD-Fabric uses several different types of network configurations.
diff --git a/deployment.rst b/deployment.rst
index 66bbe30..a0eda5b 100644
--- a/deployment.rst
+++ b/deployment.rst
@@ -5,9 +5,40 @@
Deployment Guide
================
+Deployment Overview
+-------------------
+SD-Fabric is released with Helm chart and container images.
+We recommend using **Kubernetes** and **Helm** to deploy SD-Fabric.
+Here's a list of high level steps required to deploy SD-Fabric:
-Provision Switches
-------------------
+1. **Provision switch**
+
+ We first need to install operating system with Docker and Kubernetes on the bare-metal switches.
+
+2. **Prepare switches as special Kubernetes nodes**
+
+ Kubernetes ``label`` and ``taint`` are used to configure switches as special Kubernetes worker nodes.
+ This is to make sure we deploy Stratum (and only Stratum) on switches.
+
+3. **Prepare access credential for SD-Fabric images**
+
+ SD-Fabric images are hosted on an ONF member-only Docker registry.
+ You need to obtain access token and supply that as part of the Helm value in Step 6.
+
+4. **Prepare ONOS network configuration**
+
+ Network configuration defines properties such as switch pipeconf, subnet and VLAN.
+
+5. **Prepare Stratum chassis configuration for each switch**
+
+ Chassis config defines switch properties such as port speed and breakout.
+
+6. **Install SD-Fabric** using Helm
+
+ Finally, we are going to install SD-Fabric with the information we prepared in Step 1 to 5.
+
+Step 1: 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.
@@ -49,8 +80,8 @@
4. Setup switch IP and hostname after the installation.
-Kubernetes Environment
-----------------------
+Step 2: Configure switches as special Kubernetes nodes
+------------------------------------------------------
Our `ONL <https://github.com/opennetworkinglab/OpenNetworkLinux>`_ version
includes all packages required by running the Kubernetes on top of it.
@@ -83,16 +114,8 @@
leaf2 Ready worker 27d v1.18.8
-Please follow the :ref:`Install SD-Fabric section <install_sd_fabric>` to
-check how to use Taint and NodeSelector during installation.
-
-
-# TODO
-Build Image
------------
-
-Fetch Images From Private Registry
-----------------------------------
+Step 3: Prepare access credential for SD-Fabric images
+------------------------------------------------------
Container images can be download from ONF self-hosted container registry but you have to gain the access token first.
@@ -108,107 +131,18 @@
Password:
Login Succeeded
+Step 4: Prepare ONOS network configuration
+------------------------------------------
+ See :ref:`onos_network_config` for instructions
-Please follow the :ref:`Install SD-Fabric section <install_sd_fabric>` to
-check how to use Taint and NodeSelector during installation.
+Step 5: Prepare Stratum chassis configuration
+---------------------------------------------
+ See See :ref:`stratum_chassis_config` for instructions
.. _install_sd_fabric:
-Install SD-Fabric
------------------
+Step 6: Install SD-Fabric with Helm
+-----------------------------------
To install SD-Fabric into your Kubernetes cluster, follow instructions
-described on the `SD-Fabric Helm Chart Repository <https://gerrit.opencord.org/plugins/gitiles/sdfabric-helm-charts/+/HEAD/sdfabric/README.md>`_
-
-A workflow to install the SD-Fabric should be look like
-
-1. Clone the Helm Charts files from the `SD-Fabric Helm Chart Repository <https://gerrit.opencord.org/plugins/gitiles/sdfabric-helm-charts/+/HEAD/sdfabric/README.md>`_
-2. Customize the value file based on your environment
-3. Deploy it via Helm command
-
-Below is an example how to install SD-Fabric
-
-.. note::
- Please ensure you have installed switch into Kubernetes cluster and have configured them with proper taints and label,
- and have the permission to fetch the container image from the `Aether Harbor Registry <https://registry.aetherproject.org/harbor/sign-in?redirect_url=%2Fharbor%2Fprojects>`_.
-
-
-1. Use the git command to clone the `SD-Fabric Helm Chart Repository <https://gerrit.opencord.org/plugins/gitiles/sdfabric-helm-charts/+/HEAD/sdfabric/README.md>`_
-2. Update dependencies
-
-.. code-block::
-
- ╰─$ cd sdfabric
- ╰─$ helm dep update 146 ↵
- Downloading onos-classic from repo https://charts.onosproject.org
- Downloading stratum from repo https://charts.stratumproject.org/
- Deleting outdated charts
-
-3. Prepare your value file, you can modify an existing ``values.yaml`` or use a standalone
-value file, use the later approach in this example.
-
-.. code-block::
-
- ╰─$ cat myvaules.yaml
- image:
- credential:
- username: my_username
- password: my_access_token
-
- onos-classic:
- config:
- netcfg: >
- {
- "devices": {
- "device:leaf1": {
- "segmentrouting": {
- "ipv4NodeSid": 101,
- "ipv4Loopback": "10.11.22.33",
- "routerMac": "aa:bb:cc:dd:ee:ff",
- "pairDeviceId" : "device:leaf2",
- "pairLocalPort" : 260,
- "isEdgeRouter": true,
- "adjacencySids": []
- }
- }
- }
- }
-
-
- stratum:
- nodeSelector:
- node-role.kubernetes.io: switch
-
- tolerations:
- - effect: NoSchedule
- value: switch
- key: node-role.kubernetes.io
-
-Please pay attention to the following fields.
-
- * Configure your ``registry username and password`` on image.credential
- * Configure the ``label`` on stratum.nodeSelector
- * Configure the ``taint`` on stratum.tolerations
- * Configure the ``network configuration`` on onos-classic.config.netcfg
-
-4. Verify your Configuration to ensure no YAML/Helm syntax errors
-
-.. code-block::
-
- ╰─$ helm template -f myvaules.yaml .
-
-5. Using the helm command to install it. (``helm version is above v3.2``)
-Following command will install the release `sdfabric` to namespace `sdfabric`.
-
-.. code-block::
-
- ╰─$ helm install -n sdfabric --create-namespace -f myvaules.yaml sdfabric .
- NAME: sdfabric
- LAST DEPLOYED: Mon Oct 11 11:12:59 2021
- NAMESPACE: sdfabric
- STATUS: deployed
- REVISION: 1
- TEST SUITE: None
- ╰─$ helm -n sdfabric ls
- NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
- sdfabric sdfabric 1 2021-10-11 11:12:59.178789 -0700 PDT deployed sdfabric-1.0.1
+described on the `SD-Fabric Helm Chart README <https://gerrit.opencord.org/plugins/gitiles/sdfabric-helm-charts/+/HEAD/sdfabric/README.md>`_