OPCT-36: Supporting diagrams on the documentation (#46)

https://issues.redhat.com/browse/OPCT-36

Introducing to:
-
http://127.0.0.1:8000/provider-certification-tool/support-guide/#opct-execution-flow
-
http://127.0.0.1:8000/provider-certification-tool/user-installation-review/#architecture

.github/workflows/static-website.yml

@@ -1,12 +1,11 @@
-# Simple workflow for deploying static content to GitHub Pages
 name: Deploy static content to Pages
 
 on:
-  # Runs on pushes targeting the default branch
+  # Static pages are build only targeting the main branch
   push:
     branches: ["main"]
+    paths: ['mkdocs.yml', 'docs/**', 'hack/docs-requirements.txt']
 
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
@@ -21,7 +20,6 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # Single deploy job since we're just deploying
   deploy:
     environment:
       name: github-pages
@@ -30,19 +28,22 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+
       - name: Build mkdocs website
         run: |
           sudo apt-get update
-          sudo apt-get install -y python3-pip
+          sudo apt-get install -y python3-pip graphviz
           pip3 install -r hack/docs-requirements.txt
           mkdocs build --site-dir ./site
+
       - name: Setup Pages
         uses: actions/configure-pages@v3
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1
         with:
-          # Upload entire repository
           path: './site'
+
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v1

docs/dev.md

@@ -10,8 +10,7 @@ Table of Contents:
     - [Integration with Sonobuoy CLI](#dev-integration-cli)
     - [Sonobuoy Plugins](#dev-sonobuoy-plugins)
     - [Diagrams](#dev-diagrams)
-        - [CLI commands](#dev-diagram-cli)
-        - [CLI Result filters](#dev-diagram-filters)
+    - [CLI Result filters](#dev-diagram-filters)
     - [Running Customized Certification Plugins](#dev-running-custom-plugins)
     - [Project Documentation](#dev-project-docs)
 
@@ -75,16 +74,15 @@ reader, ec, err := config.SonobuoyClient.RetrieveResults(&client.RetrieveConfig{
 
 ### Sonobuoy Plugins <a name="dev-sonobuoy-plugins"></a>
 
-*TODO* (Cert tool's plugin development is still in POC phase)
+OPCT is extended by Sonobuoy Plugins.
 
-### Diagrams <a name="dev-diagrams"></a>
+The Plugins source code is available on the project [provider-certification-plugins](https://github.com/redhat-openshift-ecosystem/provider-certification-plugins).
 
-#### CLI commands <a name="dev-diagram-cli"></a>
+### Diagrams <a name="diagrams"></a>
 
-Here's the highest level diagram showing the filenames or packages for code:
-![](./command-diagram.png)
+The diagrams are available under the page [Diagrams](./diagrams).
 
-#### CLI Result filters <a name="dev-diagram-filters"></a>
+### CLI Result filters <a name="dev-diagram-filters"></a>
 
 The CLI currently implements a few filters to help the reviewers (Partners, Support, Engineering teams) to find the root cause of the failures. The filters consumes the data sources below to improve the feedback, by plugin level, when using the command `process`:
 

docs/diagrams/.gitignore

@@ -0,0 +1,5 @@
+# Diagrams not manage as a code
+!command-diagram.png
+
+# Ignore auto generated diagrams (standard with suffix)
+*.diagram.png

docs/diagrams/cli.md

@@ -0,0 +1,4 @@
+# OPCT CLI commands
+
+Here's the highest level diagram showing the filenames or packages for code:
+![](./command-diagram.png)

docs/diagrams/index.md

@@ -0,0 +1,6 @@
+# Diagrams
+
+- [OpenShift Reference installation for OPCT](./ocp-architecture-reference.md)
+- [OPCT CLI Commnads](./cli.md)
+- [OPCT execution flow](./opct-sequence.md)
+

docs/diagrams/ocp-architecture-reference.md

@@ -0,0 +1,10 @@
+---
+hide:
+  - toc
+---
+
+# Diagram Reference Installation OpenShift
+
+Cloud Resource diagram of OpenShift HA Topology used with OPCT dedicated node:
+
+![OCP Cluster Installation Reference on Provider AWS](./ocp-ha-opct.diagram.png)

docs/diagrams/ocp-ha-opct.diagram.py

@@ -0,0 +1,41 @@
+from diagrams import Cluster, Diagram
+from diagrams.aws.compute import (
+    EC2Instances
+)
+from diagrams.aws.network import ELB
+from diagrams.k8s.infra import ( Node )
+
+from diagrams.azure.network import DNSZones
+
+with Diagram("OCP/OKD Cluster", show=False, filename="./ocp-ha-opct.diagram"):
+    dnsApiExt = DNSZones("api.<cluster>.<domain>")
+    dnsApsExt = DNSZones("*.apps.<cluster>.<domain>")
+
+    with Cluster("VPC/Network"):
+
+        with Cluster("Public subnets"):
+            lbe_api = ELB("LB API-Ext")
+            lbe_apps = ELB("LB Apps-Ext")
+
+        with Cluster("Private subnets"):
+            lbi_api = ELB("LB API-Int")
+            dnsApiInt = DNSZones("api-int.<cluster>.<domain>")
+            with Cluster("Control Plane Pool"):
+                cp_group = [EC2Instances("master-0{1,2,3}")]
+
+            with Cluster("Compute Pool"):
+                # wk_group = [EC2("compute-01"),
+                #             EC2("compute-02"),
+                #             EC2("compute-03")]
+                wk_group = [EC2Instances("compute-0{1,2,3}")]
+
+            with Cluster("OPCT Dedicated Node"):
+                ded_node = [Node("compute-04")]
+
+
+    dnsApiExt >> lbe_api >> cp_group
+    dnsApiInt >> lbi_api >> cp_group
+    cp_group >> dnsApiInt >> lbi_api
+    wk_group >> dnsApiInt >> lbi_api
+    ded_node >> dnsApiInt >> lbi_api
+    dnsApsExt >> lbe_apps >> wk_group

docs/diagrams/opct-sequence.md

@@ -0,0 +1,53 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# OPCT Execution Flow
+
+Diagram describing the default OPCT execution flow (sequence).
+
+``` mermaid
+%%{init: {"flowchart": {"useMaxWidth": false}}}%%
+
+sequenceDiagram
+  autonumber
+  OPCT->>OCP/KAS: ./opct run -w [opts]
+  loop Setup
+      OCP/KAS->>OCP/KAS: Preflight Checks
+      OCP/KAS->>OCP/KAS: Create Resources (RBAC, NS)
+  end
+  OCP/KAS->>Sonobuoy: create server
+  Sonobuoy->>Plugins: create plugins
+  loop Init
+      Plugins->>Plugins: Extract utilities
+      Plugins->>Plugins: Wait for Blocker plugin
+      Plugins->>Sonobuoy: report progress
+  end
+  Plugins->>Plugins: Plugin-N Unblocked
+  Plugins->>P_Upgrade: run cluster upgrade*
+  Note right of Plugins: *--mode=upgrade
+  P_Upgrade->>Sonobuoy: report progress
+  P_Upgrade->>Sonobuoy: save results
+  Plugins->>P_Conformance: run conformance plugins: kubernetes, openshift
+  P_Conformance->>P_Conformance: kubernetes e2e tests
+  P_Conformance->>Sonobuoy: report progress
+  P_Conformance->>Sonobuoy: save results
+
+  P_Conformance->>P_Conformance: openshift e2e tests
+  P_Conformance->>Sonobuoy: report progress
+  P_Conformance->>Sonobuoy: save results
+
+  Plugins->>P_Artifacts: run plugin: collect artifacts
+  P_Artifacts->>Sonobuoy: report progress
+  P_Artifacts->>Sonobuoy: save results
+  Sonobuoy->>OCP/KAS: collect cluster objects
+  Sonobuoy->>Sonobuoy: Post Processor
+  Sonobuoy->>Sonobuoy: Finished Artifacts
+  Sonobuoy->>OPCT: Show Summary
+  OPCT->>Sonobuoy: ./opct retrieve
+  OPCT->>OPCT: ./opct results <result>.tar.gz
+  OPCT->>OCP/KAS: ./opct destroy
+  OCP/KAS->>OPCT: Finished
+```

docs/support-guide.md

@@ -1,4 +1,4 @@
-# OpenShift Provider Certification Tool - Support Guide
+# OPCT - Support Guide
 
 - [Support Case Check List](#check-list)
     - [New Support Cases](#check-list-new-case)
@@ -14,7 +14,6 @@
     - [Review Guidelines](#review-process-guidelines)
 - [Review guide: y-stream upgrade](#upgrade-review-process)
 
-
 ## Support Case Check List <a name="check-list"></a>
 
 ### New Support Cases <a name="check-list-new-case"></a>

docs/user-installation-review.md

@@ -1,4 +1,4 @@
-# OpenShift Provider Certification Tool - Installation Review
+# Installation Review
 
 > WIP - this document is working in progress
 

docs/user.md

@@ -1,4 +1,4 @@
-# OpenShift Provider Certification Tool - User Guide
+# User Guide
 
 Welcome to the user documentation for the OpenShift Provider Certification Tool!  
 

hack/docs-requirements.txt

@@ -1 +1,6 @@
-mkdocs==1.4
+mkdocs==1.3.1
+mkdocs-material
+mkdocs-mermaid2-plugin
+
+# Require graphviz
+mkdocs-diagrams

mkdocs.yml

@@ -5,20 +5,40 @@ site_url: https://redhat-openshift-ecosystem.github.io/provider-certification-to
 repo_url: https://github.com/redhat-openshift-ecosystem/provider-certification-tool
 edit_uri: edit/main/docs/
 docs_dir: ./docs
+dev_addr: 127.0.0.1:8000
+
+markdown_extensions:
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+plugins:
+  - diagrams:
+      file_extension: ".diagram.py"
+      max_workers: 5
+  - search
 
 theme:
-  name: readthedocs
+  name: material
   highlightjs: true
   hljs_languages:
     - yaml
+  features:
+    #- toc.integrate
+    - navigation.top
 nav:
-  - "User Guide":
-      - "User Guide": "user.md"
-      - "Installation Checklist": user-installation-checklist.md
-      - "Installation Review": user-installation-review.md
-      - "Troubleshooting": troubleshooting-guide.md
-      - "Results Review": user-results-review.md
-  - "Support Guide":
-      - "Support Guide": support-guide.md
-  - "Developer Guide":
-      - "Development Guide": dev.md
+  - User Guides:
+    - "User Guide": "user.md"
+    - "Installation Checklist": user-installation-checklist.md
+    - "Installation Review": user-installation-review.md
+    - "Troubleshooting": troubleshooting-guide.md
+  - Support Guides:
+    - Support Guide: support-guide.md
+  - Developer Guides:
+    - Development Guide: dev.md
+    - Diagrams:
+      - diagrams/index.md
+      - diagrams/opct-sequence.md
+      - "Reference Architecture": diagrams/ocp-architecture-reference.md