Merge "Updating the site planning documention"
diff --git a/edge_deployment/runtime_deployment.rst b/edge_deployment/runtime_deployment.rst
index 7b3e700..231b0a7 100644
--- a/edge_deployment/runtime_deployment.rst
+++ b/edge_deployment/runtime_deployment.rst
@@ -19,7 +19,7 @@
For this, we will be using GitOps based CI/CD systems and what you will need to do is
create patches in Aether GitOps repositories, **aether-pod-configs** and **aether-app-configs**,
-to provide the cluster configurations to the CI/CD systems.
+to provide cluster and application configurations to the CI/CD systems.
.. attention::
@@ -66,6 +66,12 @@
Created ../production/ace-test/backend.tf
Created ../production/ace-test/cluster_val.tfvars
+.. attention::
+
+ If the cluster has an even number of compute nodes, edit **cluster_val.tfvars**
+ file so that only the odd number of nodes have **etcd** and **controlplane**
+ roles.
+
Create a review request.
.. code-block:: shell
@@ -80,6 +86,17 @@
It normally takes 10 - 15 minutes depending on the speed of the container images
download at the edge.
+It is also a good idea to check the system pod status after successful K8S deployment.
+To do so, login to Rancher, open the cluster that you just deployed in the **Global** view, and click
+**Launch kubectl** button. You can interact with the cluster using the window that opens.
+Run the following commands and make sure all pods are ``Running``.
+
+.. code-block:: shell
+
+ # Run kubectl commands inside here
+ # e.g. kubectl get all
+ > kubectl get po -A
+
System Application Deployment
-----------------------------
@@ -222,22 +239,26 @@
For clusters expecting minimal downtime, assign to **aether-stable**.
For clusters for development or previewing upcoming release, assign to **aether-alpha**.
-Log in to `Rancher <https://rancher.aetherproject.org>`_ as ``admin`` or ``onfadmin`` user
-and go to the **Cluster Explorer**.
-In the top left dropdown menu, click **Cluster Explorer > Continuous Delivery**.
+Workspace assignment can be done from Fleet dashboard.
+To access Fleet dashboard, log in to `Rancher <https://rancher.aetherproject.org>`_ as
+``admin`` or ``onfadmin`` user, go to the **Cluster Explorer**,
+and click **Cluster Explorer > Continuous Delivery** in the top left dropdown menu.
+Now, perform the following steps to assign the new cluster to one of the Aether workspaces.
.. image:: images/fleet-move-workspace.png
+1) Click the second dropdown menu from the left at the top and switch the current workspace
+ to **fleet-default**.
+2) Click **Clusters** on the left menu.
+3) Select the cluster.
+4) Click **Assign to...** button and choose **aether-stable** or **aether-alpha**
+ in from the popup menu.
-1) Click the second dropdown menu from the left at the top and select **fleet-default**.
-2) Select **Clusters** on the left menu and you'll see the new cluster.
-3) Click the checkbox in front of the cluster name.
-4) Select **Assign to...** button and assign the cluster to the Aether workspace.
-
-Switch the workspace to the Aether workspace, click **Clusters** in the left menu, and check the
-new cluster exists.
-Wait until the cluster state becomes **Active**.
+To verify, switch the current workspace to the workspace the cluster is assigned to,
+click **Clusters** in the left menu, and check if the cluster exists.
+Wait for the system application deployment to complete and the cluster state
+to become **Active**.
.. attention::
- Ignore BESS UPF failure at this point.
+ Ignore BESS UPF failure at this point if BESS UPF is enabled.
diff --git a/edge_deployment/vpn_bootstrap.rst b/edge_deployment/vpn_bootstrap.rst
index 11aa824..35af0fd 100644
--- a/edge_deployment/vpn_bootstrap.rst
+++ b/edge_deployment/vpn_bootstrap.rst
@@ -5,11 +5,43 @@
VPN Bootstrap
=============
-This section guides you through setting up a VPN connection between Aether Central in GCP and ACE.
+This section guides you through setting up a VPN connection between Aether
+Central in GCP and ACE.
We will be using GitOps based Aether CI/CD system for this and what you need to do is
-create a patch to Aether GitOps repository, **aether-pod-configs**, with the edge specific information.
-Note that some of the steps described here are not directly related to setting up a VPN,
-but rather are a prerequisite for adding a new ACE.
+create a patch for the new edge in **aether-pod-configs**, where all edge infrastructure
+configuration is stored.
+
+Here is a brief overview of each step. Note that some of the steps described here are not
+directly related to setting up a VPN, but are prerequisites for adding a new edge.
+
+**1. Add deployment jobs**
+Each edge has its own Jenkins jobs that build and execute an infrastructure change plan
+based on the configurations specified in aether-pod-configs.
+In this step, you'll add those jobs to Aether CI/CD system for the new edge.
+
+**2. Update global resource maps**
+aether-pod-configs maintains complete list of clusters, VPN connections, and users
+in separate global resource files. Before adding edge specific configurations,
+it is required to update those global resource maps first.
+
+**3. Generate Ansible and Terraform configs**
+In this step, you'll add Ansible and Terraform configs necessary to install and
+configure VPN softwares at the edge and set up VPN gateway, router,
+and firewall on GCP.
+
+**4. Submit your changes**
+Finally, submit your aether-pod-configs changes to run the deployment job added
+in the first step.
+
+.. attention::
+
+ If you are adding another ACE to an existing VPN connection, go to
+ :ref:`Add ACE to an existing VPN connection <add_ace_to_vpn>`.
+
+.. attention::
+
+ Make sure that UDP port 500, UDP port 4500, and ESP from **gcpvpn1.infra.aetherproject.net(35.242.47.15)**
+ and **gcpvpn2.infra.aetherproject.net(34.104.68.78)** are allowed in the firewall at the edge.
.. _add_deployment_jobs:
@@ -62,49 +94,6 @@
$ git commit -m "Add test ACE deployment job"
$ git review
-Gather VPN information
-----------------------
-
-* Make sure firewall in front of ACE allows UDP port 500, UDP port 4500, and
- ESP packets from **gcpvpn1.infra.aetherproject.net(35.242.47.15)** and
- **gcpvpn2.infra.aetherproject.net(34.104.68.78)**
-
-* Make sure that the external IP on ACE side is owned by or routed to the
- management node
-
-To help your understanding, the following sample ACE environment will be used
-in the rest of this section. Make sure to replace the sample values when you
-actually create a review request.
-
-+-----------------------------+----------------------------------+
-| Management node external IP | 66.201.42.222 |
-+-----------------------------+----------------------------------+
-| ASN | 65003 |
-+-----------------------------+----------------------------------+
-| GCP BGP IP address | Tunnel 1: 169.254.0.9/30 |
-| +----------------------------------+
-| | Tunnel 2: 169.254.1.9/30 |
-+-----------------------------+----------------------------------+
-| ACE BGP IP address | Tunnel 1: 169.254.0.10/30 |
-| +----------------------------------+
-| | Tunnel 2: 169.254.1.10/30 |
-+-----------------------------+----------------------------------+
-| PSK | UMAoZA7blv6gd3IaArDqgK2s0sDB8mlI |
-+-----------------------------+----------------------------------+
-| Management Subnet | 10.32.4.0/24 |
-+-----------------------------+----------------------------------+
-| K8S Subnet | Pod IP: 10.33.0.0/17 |
-| +----------------------------------+
-| | Cluster IP: 10.33.128.0/17 |
-+-----------------------------+----------------------------------+
-
-.. note::
- Use `this site <https://cloud.google.com/network-connectivity/docs/vpn/how-to/generating-pre-shared-key/>`_ to generate a new strong pre-shared key.
-
-.. attention::
-
- If you are adding another ACE to an existing VPN connection, go to
- :ref:`Add ACE to an existing VPN connection <add_ace_to_vpn>`
Get access to encrypted files in aether-pod-configs repository
--------------------------------------------------------------
@@ -213,15 +202,20 @@
}
.. note::
- Unless you have a specific requirement, set ASN and BGP addresses to the next available values in the map.
+ Use `this site <https://cloud.google.com/network-connectivity/docs/vpn/how-to/generating-pre-shared-key/>`_
+ to generate a strong tunnel shared secret.
+
+.. note::
+ Unless you have a specific requirement, set ASN to the next available value in the map.
+ For BGP peer IP range and address, use the next available /30 subnet in the map.
-Create Terraform and Ansible configurations
--------------------------------------------
+Generate Ansible and Terraform configurations
+---------------------------------------------
In this step, we will create a directory under ``production`` with the same name
-as the cluster, and add Terraform configurations and Ansible inventory needed
-to configure a VPN in GCP and ACE accordingly.
+as the cluster, and add Ansible and Terraform configurations needed
+to configure a VPN in ACE and GCP using a tool.
.. code-block:: shell
@@ -267,17 +261,17 @@
$ git commit -m "Add test ACE"
$ git review
-After the change is merged, wait for a while until the post-merge job finishes.
+Wait for a while until the post-merge job finishes after the change is merged.
Verify VPN connection
---------------------
You can verify the VPN connections by checking
-the routing table on the management node and trying to ping to one of the
+the routing table from the management server and trying to ping to one of the
central cluster VMs.
Be sure there are two tunnel interfaces, `gcp_tunnel1` and `gcp_tunnel2`,
-and three routing entries via one of the tunnel interfaces.
+and three additional routing entries via one of the tunnel interfaces.
.. code-block:: shell
diff --git a/index.rst b/index.rst
index e0386d3..e390ac0 100644
--- a/index.rst
+++ b/index.rst
@@ -53,7 +53,7 @@
testing/about_system_tests
testing/sdcore_testing
- testing/aether-roc-api-tests
+ testing/aether-roc-tests
testing/acceptance_specification
testing/fabric_testing
testing/pdp_testing
diff --git a/testing/aether-roc-api-tests.rst b/testing/aether-roc-api-tests.rst
deleted file mode 100644
index 9c29e73..0000000
--- a/testing/aether-roc-api-tests.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-==========================================
-Instructions For Running The ROC API Tests
-==========================================
-
-The REST API of the Aether ROC is tested utilizing the Robot Framework.
-The tests are located inside the aether-system-tests repository and they are run nightly using
-Jenkins job.
-
-Development Prerequisites
-^^^^^^^^^^^^^^^^^^^^^^^^^
-To access the ROC API from a local system, it is necessary to deploy the components of µONOS.
-This can be done with the use of Helm (see instructions on
-`this page <https://docs.onosproject.org/onos-docs/docs/content/developers/deploy_with_helm/>`_).
-
-| Additionally, it is necessary to add the sdran chart repo with the following command:
-| ``helm repo add sdran --username USER --password PASSWORD https://sdrancharts.onosproject.org``
-| , where USER and PASSWORD can be obtained from the Aether Login Information file, which is
-| accessibble to the ``onfstaff`` group.
-
-Access the ROC API
-^^^^^^^^^^^^^^^^^^
-Follow the steps below to access the ROC API:
-
-| 1. Deploy the aether-roc-umbrella chart from the sdran repo with the following command:
-| ``helm -n micro-onos install aether-roc-umbrella sdran/aether-roc-umbrella``
-| 2. Check if all pods are in a Running state with the command ``kubectl -n micro-onos get pods``
-| This should give a list like:
-
-
-+---------------------------------+-------+---------+----------+-----+
-| NAME | READY | STATUS | RESTARTS | AGE |
-+---------------------------------+-------+---------+----------+-----+
-| aether-roc-api-56f54d69d4-b4mkk | 1/1 | Running | 0 | 46s |
-+---------------------------------+-------+---------+----------+-----+
-| aether-roc-gui-75d6bf95d7-998bg | 1/1 | Running | 0 | 47s |
-+---------------------------------+-------+---------+----------+-----+
-| onos-cli-77d589f9c7-7jzcl | 1/1 | Running | 0 | 46s |
-+---------------------------------+-------+---------+----------+-----+
-| onos-config-6646dcb964-kslbs | 2/2 | Running | 0 | 46s |
-+---------------------------------+-------+---------+----------+-----+
-| onos-consensus-db-1-0 | 1/1 | Running | 0 | 46s |
-+---------------------------------+-------+---------+----------+-----+
-| onos-gui-dfd58b788-bkj6l | 2/2 | Running | 0 | 46s |
-+---------------------------------+-------+---------+----------+-----+
-| onos-topo-6948484f46-6m6fg | 1/1 | Running | 0 | 46s |
-+---------------------------------+-------+---------+----------+-----+
-| sdcore-adapter-69bff5fc45-79pld | 1/1 | Running | 0 | 47s |
-+---------------------------------+-------+---------+----------+-----+
-
-| 3. Once all pods are in a Running state, port-forward to port 8181 with the following command:
-| ``kubectl -n micro-onos port-forward $(kubectl -n micro-onos get pods -l type=api -o name) 8181``
-
-Running the tests
-^^^^^^^^^^^^^^^^^
-| 1. Checkout the aether-system-tests repo:
-| ``git clone "ssh://$GIT_USER@gerrit.opencord.org:29418/aether-system-tests"``
-| 2. Go to the repo directory:
-| ``cd aether-system-tests``
-| 3. Install the requirements:
-| ``make ast-venv``
-| 4. The ROC API test files are located inside the ``tests/roc/api`` directory. There is a test file
-| for each of the API end points. For example, we can run the test file for ``access-profile`` with
-| the following command:
-| ``robot tests/roc/api/access-profile.robot``
-| This will generate test reports and logs in the current directory.
diff --git a/testing/aether-roc-tests.rst b/testing/aether-roc-tests.rst
new file mode 100644
index 0000000..023fec4
--- /dev/null
+++ b/testing/aether-roc-tests.rst
@@ -0,0 +1,237 @@
+Instructions For Running The ROC Tests
+======================================
+
+The REST API and the GUI of the Aether ROC is tested utilizing the Robot Framework.
+The tests are located inside the aether-system-tests repository and they are run nightly using
+a Jenkins job.
+
+Development Prerequisites
+-------------------------
+To access the ROC from a local system, it is necessary to deploy the components of µONOS.
+This can be done with the use of Helm (see instructions on
+`this page <https://docs.onosproject.org/onos-docs/docs/content/developers/deploy_with_helm/>`_).
+
+Additionally, it is necessary to add the sdran chart repo with the following command:
+
+.. code-block:: shell
+
+ helm repo add sdran --username USER --password PASSWORD https://sdrancharts.onosproject.org
+
+where USER and PASSWORD can be obtained from the Aether Login Information file, which is
+accessibble to the ``onfstaff`` group.
+
+Finally, the ROC GUI tests are running on the Firefox browser, so it is nesessary to have the Firefox browser and the
+Firefox web driver (geckodriver) installed on the system in order to run these tests.
+
+Running the ROC API tests
+-------------------------
+Follow the steps below to access the ROC API:
+
+1. Deploy the aether-roc-umbrella chart from the sdran repo with the following command:
+
+.. code-block:: shell
+
+ helm -n micro-onos install aether-roc-umbrella sdran/aether-roc-umbrella
+
+2. Check if all pods are in a Running state:
+
+.. code-block:: shell
+
+ kubectl -n micro-onos get pods
+
+This should print a table like the one below:
+
+.. code-block:: shell
+
+ NAME READY STATUS RESTARTS AGE
+ aether-roc-api-df499d585-7xmt5 2/2 Running 0 2m52s
+ aether-roc-gui-56bfb5fc67-sgxh7 1/1 Running 0 2m52s
+ aether-roc-umbrella-grafana-6b4d4b55c-4mdww 1/1 Running 0 2m52s
+ aether-roc-umbrella-prometheus-alertmanager-694c449885-8fsbs 2/2 Running 0 2m52s
+ aether-roc-umbrella-prometheus-server-59c974f84-d56td 2/2 Running 0 2m52s
+ aether-roc-umbrella-sdcore-test-dummy-7f4895c59c-4pvdg 1/1 Running 0 2m52s
+ onos-cli-846d9c8df6-njqgs 1/1 Running 0 2m52s
+ onos-config-759fff55f-k9fzr 5/5 Running 0 2m52s
+ onos-consensus-store-1-0 1/1 Running 0 2m50s
+ onos-topo-56b687f77b-9l8ns 3/3 Running 0 2m52s
+ sdcore-adapter-v21-5688b8d458-5sn67 1/1 Running 0 2m52s
+ sdcore-adapter-v3-56667fd848-9szt5 2/2 Running 0 2m52s
+
+
+3. Once all pods are in a Running state, port-forward to port 8181 with the following command:
+
+.. code-block:: shell
+
+ kubectl -n micro-onos port-forward $(kubectl -n micro-onos get pods -l type=api -o name) 8181
+
+
+Now that we have access to the ROC API, we can proceed with running the ROC API tests from the ``aether-system-tests``
+repository:
+
+1. Checkout the aether-system-tests repo:
+
+.. code-block:: shell
+
+ git clone "ssh://$GIT_USER@gerrit.opencord.org:29418/aether-system-tests"
+
+2. Go to the repo directory:
+
+.. code-block:: shell
+
+ cd aether-system-tests
+
+3. Install the requirements and create a virtual environment:
+
+.. code-block:: shell
+
+ make ast-venv
+ source ast-venv/bin/activate
+
+4. Go to the ``roc`` folder and generate the ROC API test framework and test files:
+
+.. code-block:: shell
+
+ cd roc
+ python libraries/api/codegen/class_generator.py \
+ --models=variables/3_0_0_model_list.json \
+ --template=libraries/api/codegen/templates/class_template.py.tmpl \
+ --common_files_directory=libraries/api/codegen/common \
+ --target_directory=libraries/api/
+ python tests/api/codegen/tests_generator.py \
+ --models=variables/3_0_0_model_list.json \
+ --template=tests/api/codegen/templates/tests_template.robot.tmpl \
+ --target_directory=tests/api
+
+5. Go to the directory that contains the test files:
+
+.. code-block:: shell
+
+ cd tests/api/3_0_0
+
+6. Create a folder for the logs and the output files from the tests:
+
+.. code-block:: shell
+
+ mkdir results
+
+7. Run any Robot Framework test file from the ``3_0_0`` directory.
+Each test file corresponds to one of the Aether 3.0.0 models.
+
+.. code-block:: shell
+
+ robot -d results <model-name>.robot
+
+This will generate test reports and logs in the ``results`` directory.
+
+Running the ROC GUI tests
+-------------------------
+We are testing the ROC GUI by installing the ROC on a local dex server. To install the dex server, please follow
+the steps under the "Helm install" section of the Readme file in `this repository <https://github.com/onosproject/onos-helm-charts/tree/master/dex-ldap-umbrella>`_.
+
+Once that you have installed the ``dex-ldap-umbrella`` chart, follow the steps below to install the ROC
+on a local dex server:
+
+1. Deploy the aether-roc-umbrella chart from the sdran repo with the following command:
+
+.. code-block:: shell
+
+ helm -n micro-onos install aether-roc-umbrella sdran/aether-roc-umbrella --set onos-config.openidc.issuer=http://dex-ldap-umbrella:5556 --set aether-roc-gui-v3.openidc.issuer=http://dex-ldap-umbrella:5556 --set import.sdcore-adapter.v2_1.enabled=false
+
+2. Check if all pods are in a Running state:
+
+.. code-block:: shell
+
+ kubectl -n micro-onos get pods
+
+This should print a table like the one below:
+
+.. code-block:: shell
+
+ NAME READY STATUS RESTARTS AGE
+ aether-roc-api-df499d585-srf4c 2/2 Running 0 3m36s
+ aether-roc-gui-799d57456-smx6r 1/1 Running 0 3m36s
+ aether-roc-umbrella-grafana-55cccb986c-t47gz 1/1 Running 0 3m37s
+ aether-roc-umbrella-prometheus-alertmanager-694c449885-rk47g 2/2 Running 0 3m36s
+ aether-roc-umbrella-prometheus-server-59c974f84-97z5t 2/2 Running 0 3m36s
+ aether-roc-umbrella-sdcore-test-dummy-7f4895c59c-cv6j7 1/1 Running 0 3m36s
+ dex-ldap-umbrella-75bbc9d676-wfvcb 1/1 Running 0 8m36s
+ dex-ldap-umbrella-openldap-fc47667c8-9s7q4 1/1 Running 0 8m36s
+ dex-ldap-umbrella-phpldapadmin-b899f9966-rzwkr 1/1 Running 0 8m36s
+ onos-cli-846d9c8df6-kf2xk 1/1 Running 0 3m37s
+ onos-config-5568487f84-dwfs8 5/5 Running 0 3m37s
+ onos-consensus-store-1-0 1/1 Running 0 3m35s
+ onos-topo-56b687f77b-vb2sx 3/3 Running 0 3m36s
+ sdcore-adapter-v3-56667fd848-g7dh2 2/2 Running 0 3m37s
+
+
+3. Once all pods are in a Running state, port-forward to port 8183 to access the ROC GUI:
+
+.. code-block:: shell
+
+ kubectl -n micro-onos port-forward $(kubectl -n micro-onos get pods -l type=arg -o name) 8183:80
+
+3. Port-forward to port 8181 to access the ROC API (which is necessary for some test cases):
+
+.. code-block:: shell
+
+ kubectl -n micro-onos port-forward $(kubectl -n micro-onos get pods -l type=api -o name) 8181
+
+3. Finalluy, port-forward the dex service to port 5556:
+
+.. code-block:: shell
+
+ DEX_POD_NAME=$(kubectl -n micro-onos get pods -l "app.kubernetes.io/name=dex,app.kubernetes.io/instance=dex-ldap-umbrella" -o jsonpath="{.items[0].metadata.name}") &&
+ kubectl -n micro-onos port-forward $DEX_POD_NAME 5556:5556
+
+Now that we have access to the ROC API and GUI, we can proceed with running the ROC GUI tests from the
+``aether-system-tests`` repository:
+
+1. Checkout the aether-system-tests repo:
+
+.. code-block:: shell
+
+ git clone "ssh://$GIT_USER@gerrit.opencord.org:29418/aether-system-tests"
+
+2. Go to the repo directory:
+
+.. code-block:: shell
+
+ cd aether-system-tests
+
+3. Install the requirements and create a virtual environment:
+
+.. code-block:: shell
+
+ make ast-venv
+ source ast-venv/bin/activate
+
+4. Go to the ``roc`` folder and generate the ROC GUI test files:
+
+.. code-block:: shell
+
+ cd roc
+ python tests/gui/codegen/tests_generator.py \
+ --models=variables/3_0_0_model_list.json \
+ --template=tests/gui/codegen/templates/tests_template.robot.tmpl \
+ --target_directory=tests/gui
+
+5. Go to the directory that contains the test files:
+
+.. code-block:: shell
+
+ cd tests/gui/3_0_0
+
+6. Create a folder for the logs and the output files from the tests:
+
+.. code-block:: shell
+
+ mkdir results
+
+7. Run any Robot Framework test file from the ``3_0_0`` directory.
+Each test file corresponds to one of the Aether 3.0.0 models.
+
+.. code-block:: shell
+
+ robot -d results <model-name>.robot
+
+| This will generate test reports and logs in the ``results`` directory.