Document the Monitoring work (#14)

Co-authored-by: Alex Godbehere <alex.godbehere@gmail.com>
AMRC-FactoryPlus · Oct 31, 2024 · cb5023d · cb5023d
1 parent 716030d
commit cb5023d
Show file tree

Hide file tree

Showing 30 changed files with 26,148 additions and 838 deletions.
diff --git a/docs/framework-components/central/_category_.yml b/docs/framework-components/central/_category_.yml
@@ -0,0 +1,4 @@
+position: 4
+label: Central Components
+collapsible: true
+collapsed: false
diff --git a/...ponents/core-components/authorisation.mdx → ...work-components/central/authorisation.mdx b/...ponents/core-components/authorisation.mdx → ...work-components/central/authorisation.mdx
@@ -3,73 +3,28 @@ sidebar_position: 2
 ---
 
 import useBaseUrl from "@docusaurus/useBaseUrl";
+import { CentralCluster } from "../../../src/components/Clusters";
 
 # Authorisation
 
-export const ComponentOverview = () => (
-    <div className="mb-10 mx-auto text-center w-full flex justify-center">
-        <div className="p-4 bg-brand-20 dark:bg-brand-90 w-[3vw] flex items-center justify-end dark:text-white opacity-40"
-             style={{writingMode: "vertical-lr"}}>Identity
-        </div>
-        <div className="flex flex-col">
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-brand h-[3vw] opacity-40"></div>
-            <div
-                className="p-4 bg-brand-80 dark:bg-brand-40 dark:text-brand flex-1 mt-2 ml-2 w-[3vw] flex items-center justify-end text-white"
-                style={{writingMode: "vertical-lr"}}>Authorisation
-            </div>
-        </div>
-        <div className="grid grid-cols-5 gap-2">
-            <div
-                className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white col-span-full h-[3vw] flex items-center justify-end opacity-40">Identity
-            </div>
-            <div
-                className="p-4 bg-brand-80 dark:bg-brand-40 dark:text-brand col-span-full h-[3vw] flex items-center justify-end text-white">Authorisation
-            </div>
-            <div
-                className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center ml-2 opacity-40">Directory
-            </div>
-            <div
-                className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Configuration
-                Store
-            </div>
-            <div
-                className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Manager
-            </div>
-            <div
-                className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Commands
-            </div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Data
-                Warehouse
-            </div>
-            <div
-                className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40 col-span-full ml-2">MQTT
-            </div>
-            <div
-                className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40 col-span-full ml-2">Edge
-                Agent
-            </div>
-        </div>
-    </div>
-);
-
 The Authorisation component is an essential part Factory+, as it ensures that access to resources is controlled and restricted based on the permissions assigned to various principals or actors in the architecture. Access Control Lists (ACLs) are used to manage these permissions and provide a flexible way to define and manage access control policies.
 
 <OpenSourceExample buttonText={'ACS Authorisation Component'} repoUrl={'https://github.com/AMRC-FactoryPlus/acs-auth'}></OpenSourceExample>
 
 ## Overview
 
-<ComponentOverview></ComponentOverview>
+<CentralCluster hilite="authorisation"/>
 
 The Factory+ Authorisation component can be broken down into the following elements:
 
-- **Principals**: Principals are the entities (users, services, or applications) that interact with the architecture and request access to its resources. Each principal is identified using a unique ID, referred to as a UUID (Universally Unique Identifier) that conforms to RFC4122. The [Identity](/docs/framework-components/core-components/identity) component is responsible for managing the principals.
+- **Principals**: Principals are the entities (users, services, or applications) that interact with the architecture and request access to its resources. Each principal is identified using a unique ID, referred to as a UUID (Universally Unique Identifier) that conforms to RFC4122. The [Identity](/docs/framework-components/central/identity) component is responsible for managing the principals.
 - **Access Control Lists (ACLs)**: ACLs are data structures that specify the access permissions for resources in the architecture. Each entry in an ACL defines a particular action that a principal is allowed or denied to perform on a specific resource. ACLs use UUIDs to reference both the principals and the resources.
 - **Resource Management**: The resources in the architecture are managed by different components, and each component is responsible for defining its own ACLs. This allows for a decentralised approach to access control, where each component can define its own rules based on its unique requirements.
 - **Access Control Enforcement**: When a principal attempts to access a resource, the Authorisation component checks the corresponding ACLs to determine if the action is allowed. If the principal's UUID is found in the ACL with the appropriate permissions, access is granted; otherwise, access is denied.
 
 
 ### Linking Identity
-The Authorisation component in Factory+ plays a crucial role in managing the relationship between internal Principal UUIDs and [Identities](/docs/framework-components/core-components/identity). The Authorisation component maintains a mapping table that links each Principal UUID to its corresponding Kerberos principal, ensuring that access control requests from authenticated entities can be resolved. With the Principal UUID and the associated ACL information, the Authorisation component can evaluate the user's permissions on the requested resources, ensuring that only authorised actions are allowed.
+The Authorisation component in Factory+ plays a crucial role in managing the relationship between internal Principal UUIDs and [Identities](/docs/framework-components/central/identity). The Authorisation component maintains a mapping table that links each Principal UUID to its corresponding Kerberos principal, ensuring that access control requests from authenticated entities can be resolved. With the Principal UUID and the associated ACL information, the Authorisation component can evaluate the user's permissions on the requested resources, ensuring that only authorised actions are allowed.
 
 ### Access Control Entries (ACEs)
 
@@ -269,4 +224,4 @@ UUIDs of this class represent groups of permissions. The group UUID will be used
                uuid='f1fabdd1-de90-4399-b3da-ccf6c2b2c08b'
                description='Groups of accounts'/>
 
-These UUIDs represent groups of accounts which need to be granted permissions in common. These appear in the `princpal` field of an ACE.
+These UUIDs represent groups of accounts which need to be granted permissions in common. These appear in the `princpal` field of an ACE.
diff --git a/docs/framework-components/central/cluster-manager.mdx b/docs/framework-components/central/cluster-manager.mdx
@@ -0,0 +1,81 @@
+---
+sidebar_position: 9
+---
+
+import useBaseUrl from "@docusaurus/useBaseUrl";
+import { CentralCluster } from "../../../src/components/Clusters";
+import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";
+import { OpenSourceExample } from "../../../src/components/OpenSourceExample";
+
+# Cluster Manager
+
+The Cluster Manager commissions new clusters, and allows central
+services to encrypt secret information for transfer to the edge
+clusters.
+
+<OpenSourceExample buttonText={'ACS Cluster Manager Component'}
+                   repoUrl={'https://github.com/AMRC-FactoryPlus/acs-cluster-manager'}></OpenSourceExample>
+
+## Overview
+
+<CentralCluster hilite="cluster-manager"/>
+
+The Cluster Manager mainly operates autonomously, acting on requests in
+the form of Config Store entries. To create a new cluster, first a UUID must
+be allocated under the _Edge cluster_ class. Then an _Edge cluster
+configuration_ Config Store entry must be created for this object,
+specifying the details for the new cluster.
+
+The Cluster Manager will pick up the new Config Store entry automatically
+and will commission the new cluster; this consists of creating and
+populating a Git repo within the local Git server to drive the new
+cluster. The status of this process is recorded in the corresponding
+_Edge cluster setup status_ entry; once that entry has the property
+`ready: true` the cluster is created and ready to be deployed. At this
+point the URL of a bootstrap script for the new cluster can be fetched
+from the Cluster Manager via its HTTP API.
+
+This bootstrap script will attach the new cluster to the Factory+
+installation as an edge cluster, create credentials for the cluster, and
+install the edge cluster infrastructure. Once it has been run the Edge
+Sync operator will be running on the edge cluster and this will keep the
+_Edge cluster status_ Config Store entry up to date. One of the items in
+this entry is a public key which can be used to encrypt secrets such
+that only the edge cluster can decrypt them.
+
+The Cluster Manager has an API endpoint to make use of this facility.
+This endpoint will accept secret information, encrypt it, and construct
+a Kubernetes SealedSecret resource containing the encrypted data. This
+will then be committed to the cluster's driving Git repo from where Flux
+running on the edge cluster will retrieve it. The Sealed Secrets
+operator running on the edge will decrypt the secret information and
+make it available on the edge cluster as a Kubernetes Secret.
+
+## HTTP interface
+
+<OpenAPISpecRenderer url={useBaseUrl('/spec/cluster-manager.yaml')}
+    text={'the Cluster Manager component'}/>
+
+## Well-Known UUIDs
+
+These well-known UUIDs are part of the core framework and all **MUST**
+to be registered with the Configuration Store component under the
+appropriate classes.
+
+### Configuration and discovery
+
+<WellKnownUUID type='Service Function' name='Cluster Manager'
+               uuid='2706aa43-a826-441e-9cec-cd3d4ce623c2'
+               description='The Service UUID used for locating the Cluster Manager endpoints'/>
+
+<WellKnownUUID type="Class" name="Edge cluster"
+    uuid="f24d354d-abc1-4e32-98e1-0667b3e40b61"
+    description="Config Store Class used for edge cluster UUIDs"/>
+
+<WellKnownUUID type="Application" name="Edge cluster configuration"
+    uuid="bdb13634-0b3d-4e38-a065-9d88c12ee78d"
+    description="Requested configuration for an edge cluster"/>
+
+<WellKnownUUID type="Application" name="Edge cluster setup status"
+    uuid="747a62c9-1b66-4a2e-8dd9-0b70a91b6b75"
+    description="Private status entry used by the Cluster Manager"/>
diff --git a/...k-components/core-components/commands.mdx → ...framework-components/central/commands.mdx b/...k-components/core-components/commands.mdx → ...framework-components/central/commands.mdx
@@ -1,41 +1,22 @@
 ---
-sidebar_position: 6
+sidebar_position: 5
 ---
 
 import useBaseUrl from "@docusaurus/useBaseUrl";
-import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";import {OpenSourceExample} from "../../../src/components/OpenSourceExample";
+import { CentralCluster } from "../../../src/components/Clusters";
+import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";
+import {OpenSourceExample} from "../../../src/components/OpenSourceExample";
 
 # Commands
 
-export const ComponentOverview = () => (
-    <div className="mb-10 mx-auto text-center w-full flex justify-center">
-        <div className="p-4 bg-brand-20 dark:bg-brand-90 w-[3vw] flex items-center justify-end dark:text-brand opacity-40" style={{writingMode: "vertical-lr"}}>Identity</div>
-        <div className="flex flex-col">
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-brand h-[3vw] opacity-40"></div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 opacity-40 dark:text-white flex-1 mt-2 ml-2 w-[3vw] flex items-center justify-end text-brand" style={{writingMode: "vertical-lr"}}>Authorisation</div>
-        </div>
-        <div className="grid grid-cols-5 gap-2">
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-brand col-span-full h-[3vw] flex items-center justify-end opacity-40">Identity</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 opacity-40 dark:text-white col-span-full h-[3vw] flex items-center justify-end text-brand">Authorisation</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40 ml-2">Directory</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Configuration Store</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Manager</div>
-            <div className="p-4 bg-brand-80 dark:bg-brand-40 text-white dark:text-brand flex items-center justify-center">Commands</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Data Warehouse</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40 col-span-full ml-2">MQTT</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40 col-span-full ml-2">Edge Agents</div>
-        </div>
-    </div>
-);
-
 The Commands Component offers a mechanism for clients to request Sparkplug command (`NCMD`/`DCMD`) messages be issued to other clients, given appropriate authorisation. The Sparkplug specification indicates that only the Primary Application is responsible for transmitting commands, but the precise methodology and timing for this process are not explicitly defined. It is inferred that applications must interface with the Primary Application to request commands and as such the Commands Component provides the implementation for this specific aspect of the Primary Application's functionality.
 
 
 <OpenSourceExample buttonText={'ACS Commands Component'} repoUrl={'https://github.com/AMRC-FactoryPlus/acs-cmdesc'}></OpenSourceExample>
 
 ## Overview
 
-<ComponentOverview></ComponentOverview>
+<CentralCluster hilite="commands"/>
 
 ## MQTT Interface
 
@@ -229,4 +210,4 @@ The `type` is represented as one of the names used for metric types in the Spark
 The `target` of an ACE will be looked up in the Configuration Store under this application. This means static entries will need to be created for
 Sparkplug Devices intended as Commands targets.
 
-This application is documented more fully in the [Configuration Store](/docs/framework-components/core-components/configuration-store#applications) documentation.
+This application is documented more fully in the [Configuration Store](/docs/framework-components/central/configuration-store#applications) documentation.
diff --git a/...s/core-components/configuration-store.mdx → ...omponents/central/configuration-store.mdx b/...s/core-components/configuration-store.mdx → ...omponents/central/configuration-store.mdx
@@ -3,40 +3,21 @@ sidebar_position: 4
 ---
 
 import useBaseUrl from "@docusaurus/useBaseUrl";
-import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";import {OpenSourceExample} from "../../../src/components/OpenSourceExample";
+import { CentralCluster } from "../../../src/components/Clusters";
+import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";
+import {OpenSourceExample} from "../../../src/components/OpenSourceExample";
 
 # Configuration Store
 
-export const ComponentOverview = () => (
-    <div className="mb-10 mx-auto text-center w-full flex justify-center">
-        <div className="p-4 bg-brand-20 dark:bg-brand-90 w-[3vw] flex items-center justify-end dark:text-brand opacity-40" style={{writingMode: "vertical-lr"}}>Identity</div>
-        <div className="flex flex-col">
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-brand h-[3vw] opacity-40"></div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 opacity-40 dark:text-white flex-1 mt-2 ml-2 w-[3vw] flex items-center justify-end text-brand" style={{writingMode: "vertical-lr"}}>Authorisation</div>
-        </div>
-        <div className="grid grid-cols-5 gap-2">
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-brand col-span-full h-[3vw] flex items-center justify-end opacity-40">Identity</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 opacity-40 dark:text-white col-span-full h-[3vw] flex items-center justify-end text-brand">Authorisation</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40 ml-2">Directory</div>
-            <div className="p-4 bg-brand-80 dark:bg-brand-40 text-white dark:text-brand flex items-center justify-center">Configuration Store</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Manager</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Commands</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Data Warehouse</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40 col-span-full ml-2">MQTT</div>
-            <div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40 col-span-full ml-2">Edge Agents</div>
-        </div>
-    </div>
-);
-
 The Configuration Store component serves as a framework-aware centralised repository for applications utilising Factory+ to store data, settings and other information associated with Factory+ entities. Storing data centrally facilitates the sharing of metadata among applications without duplicating definitions within applications and eliminates the need to incorporate the information in the Sparkplug birth certificate, which would result in size increments with each new metadata addition.
 
 <OpenSourceExample buttonText={'ACS Configuration Store Component'} repoUrl={'https://github.com/AMRC-FactoryPlus/acs-configdb'}></OpenSourceExample>
 
 ## Overview
 
-<ComponentOverview></ComponentOverview>
+<CentralCluster hilite="configuration-store"/>
 
-Configuration Store component entries are saved as JSON documents.
+Config Store component entries are saved as JSON documents.
 
 Every category of configuration within the database is distinguished by an `Application_UUID`. While these UUIDs typically identify configuration specific to an individual application, they can also represent generic data utilised by multiple applications.
 
@@ -45,7 +26,7 @@ The fundamental design concept for the Configuration Store component stipulates
 Within the Configuration Store component, an entry can be stored for any object identified by a UUID specific to a given application. The various object types represented by UUIDs can be configured by the administrator, initially including `Applications`, `Devices`, and `Schemas`.
 
 - **Applications**, as defined above, can store global defaults using their respective `Application_UUID`.
-- **Devices** correspond to Sparkplug Devices; refer to the [Directory component specification](/docs/framework-components/core-components/directory) for information on locating a device's `Instance_UUID`.
+- **Devices** correspond to Sparkplug Devices; refer to the [Directory component specification](/docs/framework-components/central/directory) for information on locating a device's `Instance_UUID`.
 - **Schemas** pertain to Factory+ schemas as outlined in the [Schema specification](/docs/schemas) and are identified by the schema's `Schema_UUID`.
 
 ## Application Schema Requirements