From e023d2e2a82bc0998467e1737102f618ebdd0e0a Mon Sep 17 00:00:00 2001 From: Deepak Mishra Date: Thu, 5 Oct 2023 21:19:46 +0530 Subject: [PATCH 1/2] adding docs Signed-off-by: Deepak Mishra --- docs/Overloaded Terms.md | 22 +++++++++++++ docs/Sequence Diagram.md | 31 ++++++++++++++++++ docs/Terminology.md | 69 ++++++++++++++++++++++++++++++++++++++++ docs/Versioning.md | 1 + 4 files changed, 123 insertions(+) create mode 100644 docs/Overloaded Terms.md create mode 100644 docs/Sequence Diagram.md create mode 100644 docs/Terminology.md create mode 100644 docs/Versioning.md diff --git a/docs/Overloaded Terms.md b/docs/Overloaded Terms.md new file mode 100644 index 000000000..d4b3a352b --- /dev/null +++ b/docs/Overloaded Terms.md @@ -0,0 +1,22 @@ +# Overloaded terms + +These are terms which are used in different contexts by developers, product teams customers. +Each context implies a different meaning, hence they are referred here as overloaded. + +- Node +- Network +- Services +- Settings | Config +- Gossip (Sync | chatter) +- Test +- VirtualMap | Map +- Streams (sidecars streams, record stream, post consensus, pre consensus) +- Events (Pre consensus, .. ) +- Container +- Proxy (Envoy, Haproxy, JSON RPC relay ) +- Stats (CSV, Prometheus) +- Merkle +- Reconnect (TCP | on the gossip protocol) +- Recovery (Replay of preconsensus stream | disaster recovery = replay of post consensus event stream) +- Deployment + diff --git a/docs/Sequence Diagram.md b/docs/Sequence Diagram.md new file mode 100644 index 000000000..f19b728ec --- /dev/null +++ b/docs/Sequence Diagram.md @@ -0,0 +1,31 @@ +# + +## Creating a NetworkDeployment + +```mermaid +sequenceDiagram + +participant JUNIT +participant TestToolkit +participant InfrastructureAPI +participant ResourceAPI +participant HelmClient +participant K8s + + +JUNIT ->> TestToolkit: create NetworkDeployment +TestToolkit ->> InfrastructureAPI: create NetworkDeployment
NMT / Direct Install +InfrastructureAPI ->> HelmClient: deploy using helm chart +HelmClient ->> K8s: deploy resources +InfrastructureAPI ->> TestToolkit: return NetworkDeployment + +TestToolkit ->> InfrastructureAPI: Configure NetworkDeployment +InfrastructureAPI ->> ResourceAPI: get config.txt +InfrastructureAPI ->> ResourceAPI: get platform.txt +InfrastructureAPI ->> ResourceAPI: get account 101 .bin +InfrastructureAPI ->> ResourceAPI: get log4j2.xml +ResourceAPI ->> InfrastructureAPI: return config files + +InfrastructureAPI ->> HelmClient: copy all config files +InfrastructureAPI ->> HelmClient: start Node Software Pod +``` \ No newline at end of file diff --git a/docs/Terminology.md b/docs/Terminology.md new file mode 100644 index 000000000..cd8c00822 --- /dev/null +++ b/docs/Terminology.md @@ -0,0 +1,69 @@ +# Terminology + +This page collects a standard vocabulary to avoid any confusion when communicating with stakeholders. +You can refer to list of [Overloaded Terms](./Overloaded Terms.md). + +- Network Deployment + - represents everything in the k8s namespace + - Node Software Pod + - minio deployment + - mirror node deployment + - mirror node explorer + - json rpc relay + - envoy proxy + - haproxy + - A single k8s cluster can have many Network Deployment + +- Node Software Pod ( 1 k8s statefulset ) + - Hedera App Software + - Platform Software + - Side cars + - state backup uploader + - stream uploader + - record + - sidecars + - post consensus eventStreams + - account balances +- Mirror node deployment + - importer + - only handles record streams, account balances and sidecars +- Proxy deployment +- Mirror node explorer deployment +- JSON RPC replay deployment +- minio deployment + - post consesus event streams + - accountbalances + - sidecars + - record + - state backups +- Full Stack Cluster Operators + - Minio Operator, + - ~ Prometheus / Grafana Operators + - Cert Manager + - Ingress Operator + - Sealed secrets operator ? + +Settings and Configuration +- Platform Settings + - setting.txt +- Platform Configuration + - config.txt +- Node Software Address Books + - account 101 .bin + - account 102 .bin +- Node Software Logging Configuration + - log4j2.xml +- Node Software App Configuration + - platform sdk test apps + - varies + - hedera app + - bootstrap.properties + - node.properties + +Keys +- platform software gossip mutual TLS keys + - public key store + - private key store +- hedera app tls keys + - certificate + - private key \ No newline at end of file diff --git a/docs/Versioning.md b/docs/Versioning.md new file mode 100644 index 000000000..93aa28d3a --- /dev/null +++ b/docs/Versioning.md @@ -0,0 +1 @@ +# Versioning \ No newline at end of file From 645cd0d0a6d2447e767ea373a5c3cb7550a454de Mon Sep 17 00:00:00 2001 From: Deepak Mishra Date: Mon, 9 Oct 2023 22:45:18 +0530 Subject: [PATCH 2/2] adding documentation and diagrams Signed-off-by: Deepak Mishra --- docs/Sequence Diagram.md | 31 ------------------- docs/Versioning.md | 10 +++++- docs/architecture/Architecture.md | 5 +++ docs/architecture/High Level Flow Diagram.md | 3 ++ docs/architecture/architecture.drawio.svg | 4 +++ .../flow diagram-high level.drawio.svg | 4 +++ 6 files changed, 25 insertions(+), 32 deletions(-) delete mode 100644 docs/Sequence Diagram.md create mode 100644 docs/architecture/Architecture.md create mode 100644 docs/architecture/High Level Flow Diagram.md create mode 100644 docs/architecture/architecture.drawio.svg create mode 100644 docs/architecture/flow diagram-high level.drawio.svg diff --git a/docs/Sequence Diagram.md b/docs/Sequence Diagram.md deleted file mode 100644 index f19b728ec..000000000 --- a/docs/Sequence Diagram.md +++ /dev/null @@ -1,31 +0,0 @@ -# - -## Creating a NetworkDeployment - -```mermaid -sequenceDiagram - -participant JUNIT -participant TestToolkit -participant InfrastructureAPI -participant ResourceAPI -participant HelmClient -participant K8s - - -JUNIT ->> TestToolkit: create NetworkDeployment -TestToolkit ->> InfrastructureAPI: create NetworkDeployment
NMT / Direct Install -InfrastructureAPI ->> HelmClient: deploy using helm chart -HelmClient ->> K8s: deploy resources -InfrastructureAPI ->> TestToolkit: return NetworkDeployment - -TestToolkit ->> InfrastructureAPI: Configure NetworkDeployment -InfrastructureAPI ->> ResourceAPI: get config.txt -InfrastructureAPI ->> ResourceAPI: get platform.txt -InfrastructureAPI ->> ResourceAPI: get account 101 .bin -InfrastructureAPI ->> ResourceAPI: get log4j2.xml -ResourceAPI ->> InfrastructureAPI: return config files - -InfrastructureAPI ->> HelmClient: copy all config files -InfrastructureAPI ->> HelmClient: start Node Software Pod -``` \ No newline at end of file diff --git a/docs/Versioning.md b/docs/Versioning.md index 93aa28d3a..ce92997ed 100644 --- a/docs/Versioning.md +++ b/docs/Versioning.md @@ -1 +1,9 @@ -# Versioning \ No newline at end of file +# Versioning + +## Overview +We support [semantic versioning](https://semver.org/) for FST releases. +Release will be tagged with a version number in the format of `MAJOR.MINOR.PATCH` + +## Versioning Policy +Major versions of FST are not tied to the major version of Hedara releases. +Each major release version of FST will be compatible with a range of Hedera releases, as described in the release notes. diff --git a/docs/architecture/Architecture.md b/docs/architecture/Architecture.md new file mode 100644 index 000000000..60d7e89d8 --- /dev/null +++ b/docs/architecture/Architecture.md @@ -0,0 +1,5 @@ +# Architecture + +## Architecture diagram + +![Architecture Diagram](./architecture.drawio.svg) \ No newline at end of file diff --git a/docs/architecture/High Level Flow Diagram.md b/docs/architecture/High Level Flow Diagram.md new file mode 100644 index 000000000..14e7604e1 --- /dev/null +++ b/docs/architecture/High Level Flow Diagram.md @@ -0,0 +1,3 @@ +# High Level Flow Diagram + +![Flow Diagram](./flow diagram-high level.drawio.svg) \ No newline at end of file diff --git a/docs/architecture/architecture.drawio.svg b/docs/architecture/architecture.drawio.svg new file mode 100644 index 000000000..1efb6ffc8 --- /dev/null +++ b/docs/architecture/architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
Test ToolKit
Test ToolKit
Junit
Junit
CLI
CLI
Infrastructure
Infrastructure
Helm Client
Helm Client
K8s Client
K8s Client
! Work in progress !
! Work in progress !Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/architecture/flow diagram-high level.drawio.svg b/docs/architecture/flow diagram-high level.drawio.svg new file mode 100644 index 000000000..6e8de35a4 --- /dev/null +++ b/docs/architecture/flow diagram-high level.drawio.svg @@ -0,0 +1,4 @@ + + + +
processes
annotations
processes...
Junit Tests
Junit Tests
parse
YAML file
parse...
Cli
Cli
model classes
model classes
step 1
step 1
test tool kit
test tool kit
prepare values.yaml
for helm
prepare values.yaml...
helm deploy
helm deploy
get IPs of statefulset(s)
get IPs of statefulset...
get IPs of statefulset(s)
get IPs of statefulset...
create
config.txt, settings.txt
create...
[all pods] update config.txt, settings.txt
[all pods] update confi...
[all pods] copy
hedera-build.zip
[all pods] copy...
[all pods] copy
hedera-build.zip
[all pods] copy...
step 2
step 2
resource generator
resource generator
infrastructure
infrastructure
test tool kit
test tool kit
resource generator
resource generator
infrastructure
infrastructure
This is what the end users use to interact with FST, mostly indirectly.
This is what the end users use...
This is the internal API used by the test toolkit to create hedera network
This is the internal API used b...
It is mostly utility methods used to generate resources like config.txt or settings.txt
It is mostly utility methods us...
This is the entry point to FST
This is the entry point to...Text is not SVG - cannot display \ No newline at end of file