[AETHER-965] Update Jenkins topics in TOST
Change-Id: I9134817e380d5bdf2cbd580606c17838ce19272a
diff --git a/dict.txt b/dict.txt
index 661bf72..63ca643 100644
--- a/dict.txt
+++ b/dict.txt
@@ -1,6 +1,6 @@
aether
-Ansible
ansible
+Ansible
config
configs
controlplane
@@ -13,38 +13,46 @@
ethernet
gerrit
Grafana
+IaC
+Jenkins
+jjb
Kubernetes
-IaaC
LTE
macroENB
mainboard
+menlo
Menlo
Menlo Park
namespace
omec
+onos
ONOS
patchset
pfcp
PFCP
provisioner
repo
+repos
repository
reStructuredText
runtime
+Sercomm
Speedtest
subnet
SupportedTAs
tAC
+telegraf
Telegraf
Terraform
tfvars
Tofino
+tost
TOST
upf
UPF
virtualenv
-Wireshark
vpn
-YAML
+Wireshark
yaml
-Sercomm
+YAML
+makefile
diff --git a/pronto_deployment_guide/images/jenkins-onos-params.png b/pronto_deployment_guide/images/jenkins-onos-params.png
index 1756228..597f326 100644
--- a/pronto_deployment_guide/images/jenkins-onos-params.png
+++ b/pronto_deployment_guide/images/jenkins-onos-params.png
Binary files differ
diff --git a/pronto_deployment_guide/tost_deployment.rst b/pronto_deployment_guide/tost_deployment.rst
index 12acef4..103182c 100644
--- a/pronto_deployment_guide/tost_deployment.rst
+++ b/pronto_deployment_guide/tost_deployment.rst
@@ -23,37 +23,37 @@
staging/ace-menlo/tost
├── app_map.tfvars
├── backend.tf
- ├── common
- │ ├── main.tf
- │ └── variables.tf
- ├── hostpath.yaml
- ├── main.tf
+ ├── deepinsight
+ │ ├── README.md
+ │ ├── deepinsight-topo.json
+ │ └── deepinsight-topo.json.license
+ ├── main.tf -> ../../../common/tost/main.tf
├── onos
- │ ├── app_map.tfvars
- │ ├── backend.tf
- │ ├── main.tf -> ../common/main.tf
- │ ├── onos-netcfg.json
- │ ├── onos-netcfg.json.license
- │ ├── onos.yaml
- │ └── variables.tf -> ../common/variables.tf
+ │ ├── app_map.tfvars
+ │ ├── backend.tf
+ │ ├── main.tf -> ../../../../common/tost/apps/onos/main.tf
+ │ ├── onos-netcfg.json
+ │ ├── onos-netcfg.json.license
+ │ ├── onos.yaml
+ │ └── variables.tf -> ../../../../common/tost/apps/onos/variables.tf
├── stratum
- │ ├── app_map.tfvars
- │ ├── backend.tf
- │ ├── main.tf -> ../common/main.tf
- │ ├── menlo-staging-leaf-1-chassis-config.pb.txt
- │ ├── menlo-staging-leaf-2-chassis-config.pb.txt
- │ ├── menlo-staging-spine-1-chassis-config.pb.txt
- │ ├── menlo-staging-spine-2-chassis-config.pb.txt
- │ ├── stratum.yaml
- │ ├── tost-dev-chassis-config.pb.txt
- │ └── variables.tf -> ../common/variables.tf
+ │ ├── app_map.tfvars
+ │ ├── backend.tf
+ │ ├── main.tf -> ../../../../common/tost/apps/stratum/main.tf
+ │ ├── menlo-staging-leaf-1-chassis-config.pb.txt
+ │ ├── menlo-staging-leaf-2-chassis-config.pb.txt
+ │ ├── menlo-staging-spine-1-chassis-config.pb.txt
+ │ ├── menlo-staging-spine-2-chassis-config.pb.txt
+ │ ├── stratum.yaml
+ │ ├── tost-dev-chassis-config.pb.txt
+ │ └── variables.tf -> ../../../../common/tost/apps/stratum/variables.tf
├── telegraf
- │ ├── app_map.tfvars
- │ ├── backend.tf
- │ ├── main.tf -> ../common/main.tf
- │ ├── telegraf.yaml
- │ └── variables.tf -> ../common/variables.tf
- └── variables.tf
+ │ ├── app_map.tfvars
+ │ ├── backend.tf
+ │ ├── main.tf -> ../../../../common/tost/apps/telegraf/main.tf
+ │ ├── telegraf.yaml
+ │ └── variables.tf -> ../../../../common/tost/apps/telegraf/variables.tf
+ └── variables.tf -> ../../../common/tost/variables.tf
There are four Terraform scripts inside **tost** directory and are responsible for managing each service.
@@ -274,6 +274,35 @@
sample_interval: 5000ns
subscription_mode: sample
+
+Create Your Own Configs
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The easiest way to create your own configs is running the template script.
+
+Assumed we would like to set up the **ace-example** pod in the production environment.
+
+1. open the **tools/ace_env**
+2. fill out all required variables
+3. import the environment variables from **tools/ace_env**
+4. perform the makefile command to generate configuration and directory for TOST
+5. update **onos-netcfg.json** for ONOS
+6. update **${hostname}-chassis-config.pb.txt** for Stratum
+7. update all switch IPs in **telegraf.yaml**
+8. commit your change and open the Gerrit patch
+
+.. code-block:: console
+
+ vim tools/ace_env
+ source tools/ace_env
+ make -C tools/ tost
+ vim production/ace-example/tost/onos/onos-netcfg.json
+ vim production/ace-example/tost/stratum/*${hostname}-chassis-config.pb.txt**
+ vim production/ace-example/tost/telegraf/telegraf.yam
+ git add commit
+ git review
+
+
Quick recap
^^^^^^^^^^^
@@ -298,9 +327,31 @@
=====================================
There are three major components in the Jenkins system, the Jenkins pipeline and Jenkins Job Builder and Jenkins Job.
-.. note::
+We follow the Infrastructure as Code principle to place three major components in a Git repo, **aether-ci-management**
+Download **aether-ci-management** repository .
- All Jenkins related files are placed in a `temporary repository <https://github.com/hwchiu/stratum-example/tree/master/pipelines>`_ and will move to another repo once the Aether Jenkins is ready.
+.. code-block:: shell
+
+ $ cd $WORKDIR
+ $ git clone "ssh://[username]@gerrit.opencord.org:29418/aether-ci-management"
+
+
+Here is the example of folder structure, we put everything related to three major components under the jjb folder.
+
+.. code-block:: console
+
+ $ tree -d jjb
+ jjb
+ ├── ci-management
+ ├── global
+ │ ├── jenkins-admin -> ../../global-jjb/jenkins-admin
+ │ ├── jenkins-init-scripts -> ../../global-jjb/jenkins-init-scripts
+ │ ├── jjb -> ../../global-jjb/jjb
+ │ └── shell -> ../../global-jjb/shell
+ ├── pipeline
+ ├── repos
+ ├── shell
+ └── templates
Jenkins pipeline
@@ -318,6 +369,41 @@
Instead, we perform the clean installation.
In the pipeline script, Terraform will destroy all existing resources and then create them again.
+
+We put all pipeline scripts under the pipeline directory, the language of the pipeline script is groovy.
+
+.. code-block:: console
+
+ $ tree pipeline
+ pipeline
+ ├── aether-in-a-box.groovy
+ ├── artifact-release.groovy
+ ├── cd-pipeline-charts-postrelease.groovy
+ ├── cd-pipeline-dockerhub-postrelease.groovy
+ ├── cd-pipeline-postrelease.groovy
+ ├── cd-pipeline-terraform.groovy
+ ├── docker-publish.groovy
+ ├── ng40-func.groovy
+ ├── ng40-scale.groovy
+ ├── reuse-scan-gerrit.groovy
+ ├── reuse-scan-github.groovy
+ ├── tost-onos.groovy
+ ├── tost-stratum.groovy
+ ├── tost-telegraf.groovy
+ └── tost.groovy
+
+Currently, we had four pipeline scripts for TOST deployment.
+
+1. tost-onos.groovy
+2. tost-stratum.groovy
+3. tost-telegraf.groovy
+4. tost.groovy
+
+tost-[onos/stratum/telegraf].groovy are used to deploy the individual application respectively,
+and tost.groovy is a high level script, used to deploy the TOST application, it will execute
+the above three scripts in its pipeline script.
+
+
Jenkins jobs
^^^^^^^^^^^^
@@ -340,13 +426,12 @@
Application level
"""""""""""""""""
-- **config_review/config_patchset** tell the pipeline script to read the config for ONOS from a specified
- gerrit review, instead of the HEAD branch. It’s good for developer to test its change before merge.
-- **onos_user/onos_password**: used to login ONOS controller
- **onos_password** is a key which will load the real password from Jenkins Credential system.
-- **onos_ns**: the namespace we installed the secret file for ONOS, (will refactor in the future).
+- **GERRIT_CHANGE_NUMBER/GERRIT_PATCHSET_NUMBER**: tell the pipeline script to read
+ the config for aether-pod-configs repo from a specified gerrit review, instead of the
+ HEAD branch. It’s good for developer to test its change before merge.
+- **onos_user**: used to login ONOS controller
- **git_repo/git_server/git_user/git_password_env**: information of git repository, **git_password_env** is a key for
- Jenkins Credential system.
+ Jenkins Credential system.
Cluster level
"""""""""""""
@@ -354,32 +439,180 @@
- **terraform_dir**: The root directory of the TOST directory.
- **rancher_cluster**: target Rancher cluster name.
- **rancher_api_env**: Rancher credential to access Rancher, used by Terraform.
-- **k8s_conifg**: Kubernetes config to access remote Kubernetes cluster.
.. note::
- Typically, developer only focus on **config_review** and **config_patchset**. The rest of them are managed by OPs.
+ Typically, developer only focus on **GERRIT_CHANGE_NUMBER** and **GERRIT_PATCHSET_NUMBER**. The rest of them are managed by OPs.
Jenkins Job Builder (JJB)
^^^^^^^^^^^^^^^^^^^^^^^^^
-We prefer to apply the IaaC (Infrastructure as a Code) for everything.
+
+We prefer to apply the IaC (Infrastructure as Code) for everything.
We use the JJB (Jenkins Job Builder) to create new Jenkins Job, including the Jenkins pipeline.
We need to clone a set of Jenkins jobs when a new edge is deployed.
-..
- TODO: Automate Jenkins job creation with JJB once the Aether Jenkins is set updated
+In order to provide the flexibility and avoid re-inventing the wheel, we used the job template to declare your job.
+Thanks to the JJB, we can use the parameters in the job template to render different kinds of jobs easily.
+
+All the template files are placed under templates directory.
+
+.. code-block:: console
+
+ ╰─$ tree templates
+ templates
+ ├── aether-in-a-box.yaml
+ ├── archive-artifacts.yaml
+ ├── artifact-release.yml
+ ├── cd-pipeline-terraform.yaml
+ ├── docker-publish-github.yaml
+ ├── docker-publish.yaml
+ ├── helm-lint.yaml
+ ├── make-test.yaml
+ ├── ng40-nightly.yaml
+ ├── ng40-test.yaml
+ ├── private-docker-publish.yaml
+ ├── private-make-test.yaml
+ ├── publish-helm-repo.yaml
+ ├── reuse-gerrit.yaml
+ ├── reuse-github.yaml
+ ├── sync-dir.yaml
+ ├── tost.yaml
+ ├── verify-licensed.yaml
+ └── versioning.yaml
+
+
+we defined all TOST required job templates in tost.yaml and here is its partial content.
+
+.. code-block:: yaml
+
+ - job-template:
+ name: "{name}-onos"
+ id: "deploy-onos"
+ project-type: pipeline
+ dsl: !include-raw-escape: jjb/pipeline/tost-onos.groovy
+ triggers:
+ - onf-infra-tost-gerrit-trigger:
+ gerrit-server-name: '{gerrit-server-name}'
+ trigger_command: "apply"
+ pattern: "{terraform_dir}/tost/onos/.*"
+ logrotate:
+ daysToKeep: 7
+ numToKeep: 10
+ artifactDaysToKeep: 7
+ artifactNumToKeep: 10
+ parameters:
+ - string:
+ name: gcp_credential
+ default: "{google_bucket_access}"
+ - string:
+ name: rancher_cluster
+ default: "{rancher_cluster}"
+ - string:
+ name: rancher_api_env
+ default: "{rancher_api}"
+ - string:
+ name: git_repo
+ default: "aether-pod-configs"
+ - string:
+ name: git_server
+ default: "gerrit.opencord.org"
+ - string:
+ name: git_ssh_user
+ default: "jenkins"
+
+
+
+
+Once we have the job template, we need to tell the JJB, we want to use the job template to create our own jobs.
+Here comes the concept of project, you need to define job templates you want to use and the values of all parameters.
+
+
+We put all project yaml files under the repo directory and here is the example
+
+.. code-block:: console
+
+ ╰─$ tree repos 130 ↵
+ repos
+ ├── aether-helm-charts.yaml
+ ├── aether-in-a-box.yaml
+ ├── cd-pipeline-terraform.yaml
+ ├── ng40-test.yaml
+ ├── spgw.yaml
+ └── tost.yaml
+
+
+Following is the example of tost projects, we defined three projects here, and each project has different
+parameters and Jenkins jobs it wants to use.
+
+.. code-block:: yaml
+
+ - project:
+ name: deploy-menlo-tost-dev
+ rancher_cluster: "menlo-tost-dev"
+ terraform_dir: "testing/menlo-tost"
+ rancher_api: "{rancher_testing_access}"
+ jobs:
+ - "deploy"
+ - "deploy-onos"
+ - "deploy-stratum"
+ - "deploy-telegraf"
+ - project:
+ name: deploy-menlo-tost-staging
+ rancher_cluster: "ace-menlo"
+ terraform_dir: "staging/ace-menlo"
+ rancher_api: "{rancher_staging_access}"
+ jobs:
+ - "deploy"
+ - "deploy-onos"
+ - "deploy-stratum"
+ - "deploy-telegraf"
+ - project:
+ name: deploy-menlo-production
+ rancher_cluster: "ace-menlo"
+ terraform_dir: "production/ace-menlo"
+ rancher_api: "{rancher_production_access}"
+ jobs:
+ - "deploy"
+ - "deploy-onos"
+ - "deploy-stratum"
+ - "deploy-telegraf"
+
+
+Create Your Own Jenkins Job
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Basically, if you don't need to customize the Jenkins pipeline script and the job configuration, the only thing
+you need to do is modify the repos/tost.yaml to add your project.
+
+For example, we would like to deploy the TOST to our production pod, let's assume it named "tost-example".
+Add the following content into repos/tost.yaml
+
+.. code-block:: yaml
+
+ - project:
+ name: deploy-tost-example-production
+ rancher_cluster: "ace-test-example"
+ terraform_dir: "production/tost-example"
+ rancher_api: "{rancher_production_access}"
+ jobs:
+ - "deploy"
+ - "deploy-onos"
+ - "deploy-stratum"
+ - "deploy-telegraf"
+
+
+.. note::
+
+ The **terraform_dir** indicates the directory location in aether-pod-configs repo, please ensure your Terraform scripts
+ already there before running the Jenkins job.
+
Trigger TOST deployment in Jenkins
==================================
-Ideally, whenever a change is merged into **aether-pod-config**,
+Whenever a change is merged into **aether-pod-config**,
the Jenkins job should be triggered automatically to (re)deploy TOST.
-This is still being set up at this moment.
-Therefore, we need to manually trigger the deployment by clicking the **Build** button
-of each Jenkins job and provide parameters accordingly.
-..
- TODO: Update this once the gerrit trigger is implemented
-
+You can also type the comment **apply** in the Gerrit patch, it will trigger Jenkins jobs to deploy TOST for you.
Troubleshooting
===============
