Issue #25: DSS to explain the topologie of this infrastructure

README.md

@@ -5,6 +5,14 @@ In this repository, you can find the Kubernetes manifests that deploy each of
 the applications on the three different cloud providers: Google Cloud Platform
 (GCP), Amazon Web Services (AWS), and Azure.
 
+## Documentation
+
+For more information about this project, you can refer to the documentation
+which contains explanations as well as diagrams:
+
+- [Global overview](docs/global_overview.md)
+- [Ingress](docs/ingress.md)
+
 ## Content
 
 - The Terraform configuration for the GCP cluster.
@@ -26,6 +34,6 @@ and Cert Manager to meet our requirements.
 - [Ingress NGINX](https://docs.nginx.com/nginx-ingress-controller/)
 - [OTEL](https://opentelemetry.io/)
 
-## Liens utiles
+## Useful links
 
 [ai-cfia github container registry](https://github.com/orgs/ai-cfia/packages)

docs/global_overview.md

@@ -0,0 +1,171 @@
+# Generic architecture
+
+## Executive summary
+
+These diagrams in question provide a visual representation of the planned
+infrastructure strategy for the ai-lab at the Canadian Food Inspection Agency
+(CFIA). The reason for this design is to cater to the needs of users spread
+across the vast expanse of Canada, including major user groups in canada central
+and canada east. By establishing two clusters in the Central and Eastern
+geographic regions of Canada, the CFIA aims to deliver optimal service to
+all users regardless of their location. This approach not only ensures high
+availability (HA) by mitigating the risk of service disruption due to regional
+outages but also maintains a one-to-one redundancy of all services, which is
+crucial for disaster recovery and uninterrupted operations. The strategic
+placement of these clusters allows for efficient data replication and swift
+failover processes, thereby providing a robust and reliable infrastructure for
+the agency's critica operations.
+
+## Glossary
+
+**Kubernetes:** Kubernetes is an open-source platform designed to automate
+deploying, scaling, and operating application containers. It groups containers
+that make up an application into logical units for easy management and
+discovery. Kubernetes provides tools for orchestrating distributed
+systems at scale.
+
+**Pod:** In the context of Kubernetes, a Pod is the smallest deployable unit
+that can be created and managed. It represents a single instance of a running
+process in your cluster and can contain one or more containers that share
+storage, network, and a specification on how to run the containers. Pods are
+ephemeral by nature and can be replaced by Kubernetes in case of node
+failure or other events.
+
+**Ingress:** Ingress refers to the act of entering or the ability to enter.
+n the context of networking and computing, it typically denotes incoming traffic
+to a network or service from an external source.
+
+**Load balancer**: A load balancer is a system that distributes network or
+application traffic across a number of servers to ensure no single server
+becomes overwhelmed, improving the reliability and performance of applications.
+It helps to prevent server overload, manage failover, and increase
+the availability of a website or service by automatically routing client
+requests to the most suitable server.
+
+**High availability (HA):** High availability (HA) refers to systems that are
+designed to be operational and accessible without significant downtime.
+This is achieved through redundancy and failover mechanisms, ensuring that if
+one component fails, another can take over seamlessly to maintain service
+continuity. The goal of HA is to minimize the chances of service interruption
+due to hardware failures, maintenance, or unexpected outages.
+
+**Azure:**: Azure is a cloud computing service created by Microsoft for
+building, testing, deploying, and managing applications and services through
+Microsoft-managed data centers. It provides a range of cloud services,
+including those for computing, analytics, storage, and networking. Users
+can pick and choose from these services to develop and scale new applications,
+or run existing applications in the public cloud.
+
+In Canada, Azure has two regions: **Canada Central (CA)**
+and **Canada East (CE)**. Canada Central is located in Toronto and is designed
+to offer low latency to financial services and other businesses in the area.
+Canada East, located in Quebec City, provides French language service support
+and disaster recovery for businesses that require data residency within
+the province of Quebec.
+
+**Virtual network (VNet)**: A virtual network in the cloud is a simulated
+network environment that provides a logical separation of resources within a
+cloud computing platform. It enables users to define their own network topology,
+manage IP addresses, configure firewalls, and set up subnets and route tables,
+all within a secure and isolated space that mimics the functionality of a
+traditional network.
+
+## Diagrams
+
+1. Describe the operation of our implementation for high availability (HA)
+as well as the redundancy of services within Azure using Kubernetes
+
+```mermaid
+flowchart
+    subgraph Azure["Azure"]
+        direction TB
+        subgraph CC["Canada central (CA)"]
+            subgraph VNet1["VNet-CC"]
+                subgraph Kubernetes1["Kubernetes-CC"]
+                    direction TB
+                    Ingress1["Ingress"]
+                    Pod1["Pod"]
+                    Pod2["Pod"]
+                    Pod3["Pod"]
+                    Pod4["Pod"]
+                    Pod5["Pod"]
+                    Pod6["Pod"]
+                end
+            end
+        end
+
+        subgraph CE["Canada east (CE)"]
+            subgraph VNet2["VNet-CE"]
+                subgraph Kubernetes2["Kubernetes-CE"]
+                    direction TB
+                    Ingress2["Ingress"]
+                    Pod7["Pod"]
+                    Pod8["Pod"]
+                    Pod9["Pod"]
+                    Pod10["Pod"]
+                    Pod11["Pod"]
+                    Pod12["Pod"]
+                end
+            end
+        end
+
+        VNet1["VNet-CC"] <--->|HA| VNet2["VNet-CE"]
+        Kubernetes1["Kubernetes-CC"] <--->|1:1 redundancy| Kubernetes2["Kubernetes-CE"]
+    end
+```
+
+2. Represents the process of sending a request to our infrastructure
+within Azure
+```mermaid
+flowchart
+    Client["Client"] -->|request| LB
+    subgraph Azure["Azure"]
+        LB["Load balancer"]
+        LB --> VNet1
+        LB --> VNet2
+        direction LR
+        subgraph CC["Canada central (CC)"]
+            subgraph VNet1["VNet-CC"]
+                subgraph Kubernetes1["Kubernetes-CC"]
+                    direction TB
+                    Ingress1["Ingress"]
+                    Pod1["Pod"]
+                    Pod2["Pod"]
+                    Pod3["Pod"]
+                    Pod4["Pod"]
+                    Pod5["Pod"]
+                    Pod6["Pod"]
+                end
+            end
+        end
+
+        subgraph CE["Canada east (CE)"]
+            subgraph VNet2["VNet-CE"]
+                subgraph Kubernetes2["Kubernetes-CE"]
+                    direction TB
+                    Ingress2["Ingress"]
+                    Pod7["Pod"]
+                    Pod8["Pod"]
+                    Pod9["Pod"]
+                    Pod10["Pod"]
+                    Pod11["Pod"]
+                    Pod12["Pod"]
+                end
+            end
+        end
+    end
+```
+
+3. Representation of the two diagrams above in one
+
+![Diagram](svg/ha_redundancy_lb.svg)
+
+## References
+
+[Kubernetes](https://kubernetes.io/docs/concepts/overview/)
+
+[Pod](https://kubernetes.io/docs/concepts/workloads/pods/)
+
+[HA](https://www.techtarget.com/searchdatacenter/definition/high-availability)
+
+[Load balancer](https://www.nginx.com/resources/glossary/load-balancing/)

docs/ingress.md

@@ -0,0 +1,78 @@
+# Multi layered application
+
+## Executive summary
+
+In our multi layered architecture, the frontend and backend of our applications
+are intricately linked, with the backend coded in Python and the frontend in
+TypeScript, each residing in their respective directories. The backend not only
+processes requests but also occasionally interacts with various object storage
+solutions, such as AI models, databases, and blob storage, to manage and
+retrieve data. This interaction is crucial for the seamless operation of our
+services and is depicted in the accompanying of sequence diagrams, which
+illustrates the flow of a request from the frontend through the ingress to the
+backend.
+
+## Glossary
+
+**Frontend:** Frontend refers to the part of a website or application that users
+interact with directly, encompassing the design, layout, and behavior that
+people experience within a web browser or app interface.
+
+**Backend:** The backend refers to the server-side of a web application,
+encompassing the database, server, and application logic that process user
+requests and perform the core functional operations of the system.
+
+**Database:** A database is a structured collection of data that is stored and
+accessed electronically, designed to manage, query, and retrieve information
+efficiently.
+
+**Ingress:** Ingress refers to the act of entering or the ability to enter.
+n the context of networking and computing, it typically denotes incoming traffic
+to a network or service from an external source.
+
+**Browser:** A browser, also known as a web browser, is a software application
+used to access, retrieve, and view content on the World Wide Web, including
+webpages,  images, videos, and other multimedia. It interprets HTML and other
+web technologies to present information in an accessible format.
+
+## Diagram
+
+This diagram shows the communication between the `frontend`, the
+`backend (/api)`, the `browser (client)`, and the `ingress (ingress nginx)`
+for an application.
+```mermaid
+sequenceDiagram
+    participant Browser
+    participant Ingress
+    participant Frontend
+    participant Backend
+
+    Note over Browser,Backend: DNS https://inspection.alpha.canada.ca resolves to Ingress IP with A record
+    Note over Browser,Backend: https://*.inspection.alpha.canada.ca * is any CNAME to the DNS
+
+    Browser->>Ingress: GET / https://*.inspection.alpha.canada.ca
+    Ingress->>Frontend: GET /
+    Frontend-->>Ingress: 200
+    Ingress-->>Browser: The browser display the result
+
+    Browser->>Ingress: GET /api/search https://*.inspection.alpha.canada.ca/api/search/
+    Ingress->>Backend: GET /search
+    Note over Ingress: /api is /search (ImplementationSpecific)
+    Backend-->>Ingress: 200
+    Ingress-->>Browser: The browser display the result
+```
+
+## References
+
+[Ingress NGINX](https://docs.nginx.com/nginx-ingress-controller/)
+
+[Ingress NGINX - ImplementationSpecific](
+https://docs.nginx.com/nginx-ingress-controller/configuration/ingress-resources/basic-configuration/)
+
+[DNS](https://www.fortinet.com/resources/cyberglossary/what-is-dns)
+
+[DNS - A record](
+https://support.google.com/a/answer/2576578?hl=en#zippy=%2Chow-a-records-work%2Cconfigure-a-records-now)
+
+[DNS - CNAME record](
+https://support.google.com/a/answer/112037?hl=en#zippy=%2Cset-up-cname-records-now)