Skip to content

Commit cb5023d

Browse files
amrc-benmorrowAlexGodbehere
amrc-benmorrow
and
AlexGodbehere
authored
Document the Monitoring work (#14)
Co-authored-by: Alex Godbehere <[email protected]>
1 parent 716030d commit cb5023d

30 files changed

+26148
-838
lines changed

‎docs/framework-components/central/_category_.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
position: 4
2+
label: Central Components
3+
collapsible: true
4+
collapsed: false

‎docs/framework-components/core-components/authorisation.mdx renamed to ‎docs/framework-components/central/authorisation.mdx

Lines changed: 5 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -3,73 +3,28 @@ sidebar_position: 2
33
---
44

55
import useBaseUrl from "@docusaurus/useBaseUrl";
6+
import { CentralCluster } from "../../../src/components/Clusters";
67

78
# Authorisation
89

9-
export const ComponentOverview = () => (
10-
<div className="mb-10 mx-auto text-center w-full flex justify-center">
11-
<div className="p-4 bg-brand-20 dark:bg-brand-90 w-[3vw] flex items-center justify-end dark:text-white opacity-40"
12-
style={{writingMode: "vertical-lr"}}>Identity
13-
</div>
14-
<div className="flex flex-col">
15-
<div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-brand h-[3vw] opacity-40"></div>
16-
<div
17-
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"
18-
style={{writingMode: "vertical-lr"}}>Authorisation
19-
</div>
20-
</div>
21-
<div className="grid grid-cols-5 gap-2">
22-
<div
23-
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
24-
</div>
25-
<div
26-
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
27-
</div>
28-
<div
29-
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
30-
</div>
31-
<div
32-
className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Configuration
33-
Store
34-
</div>
35-
<div
36-
className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Manager
37-
</div>
38-
<div
39-
className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Commands
40-
</div>
41-
<div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-white text-brand flex items-center justify-center opacity-40">Data
42-
Warehouse
43-
</div>
44-
<div
45-
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
46-
</div>
47-
<div
48-
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
49-
Agent
50-
</div>
51-
</div>
52-
</div>
53-
);
54-
5510
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.
5611

5712
<OpenSourceExample buttonText={'ACS Authorisation Component'} repoUrl={'https://github.com/AMRC-FactoryPlus/acs-auth'}></OpenSourceExample>
5813

5914
## Overview
6015

61-
<ComponentOverview></ComponentOverview>
16+
<CentralCluster hilite="authorisation"/>
6217

6318
The Factory+ Authorisation component can be broken down into the following elements:
6419

65-
- **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.
20+
- **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.
6621
- **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.
6722
- **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.
6823
- **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.
6924

7025

7126
### Linking Identity
72-
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.
27+
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.
7328

7429
### Access Control Entries (ACEs)
7530

@@ -269,4 +224,4 @@ UUIDs of this class represent groups of permissions. The group UUID will be used
269224
uuid='f1fabdd1-de90-4399-b3da-ccf6c2b2c08b'
270225
description='Groups of accounts'/>
271226

272-
These UUIDs represent groups of accounts which need to be granted permissions in common. These appear in the `princpal` field of an ACE.
227+
These UUIDs represent groups of accounts which need to be granted permissions in common. These appear in the `princpal` field of an ACE.

‎docs/framework-components/central/cluster-manager.mdx

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
sidebar_position: 9
3+
---
4+
5+
import useBaseUrl from "@docusaurus/useBaseUrl";
6+
import { CentralCluster } from "../../../src/components/Clusters";
7+
import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";
8+
import { OpenSourceExample } from "../../../src/components/OpenSourceExample";
9+
10+
# Cluster Manager
11+
12+
The Cluster Manager commissions new clusters, and allows central
13+
services to encrypt secret information for transfer to the edge
14+
clusters.
15+
16+
<OpenSourceExample buttonText={'ACS Cluster Manager Component'}
17+
repoUrl={'https://github.com/AMRC-FactoryPlus/acs-cluster-manager'}></OpenSourceExample>
18+
19+
## Overview
20+
21+
<CentralCluster hilite="cluster-manager"/>
22+
23+
The Cluster Manager mainly operates autonomously, acting on requests in
24+
the form of Config Store entries. To create a new cluster, first a UUID must
25+
be allocated under the _Edge cluster_ class. Then an _Edge cluster
26+
configuration_ Config Store entry must be created for this object,
27+
specifying the details for the new cluster.
28+
29+
The Cluster Manager will pick up the new Config Store entry automatically
30+
and will commission the new cluster; this consists of creating and
31+
populating a Git repo within the local Git server to drive the new
32+
cluster. The status of this process is recorded in the corresponding
33+
_Edge cluster setup status_ entry; once that entry has the property
34+
`ready: true` the cluster is created and ready to be deployed. At this
35+
point the URL of a bootstrap script for the new cluster can be fetched
36+
from the Cluster Manager via its HTTP API.
37+
38+
This bootstrap script will attach the new cluster to the Factory+
39+
installation as an edge cluster, create credentials for the cluster, and
40+
install the edge cluster infrastructure. Once it has been run the Edge
41+
Sync operator will be running on the edge cluster and this will keep the
42+
_Edge cluster status_ Config Store entry up to date. One of the items in
43+
this entry is a public key which can be used to encrypt secrets such
44+
that only the edge cluster can decrypt them.
45+
46+
The Cluster Manager has an API endpoint to make use of this facility.
47+
This endpoint will accept secret information, encrypt it, and construct
48+
a Kubernetes SealedSecret resource containing the encrypted data. This
49+
will then be committed to the cluster's driving Git repo from where Flux
50+
running on the edge cluster will retrieve it. The Sealed Secrets
51+
operator running on the edge will decrypt the secret information and
52+
make it available on the edge cluster as a Kubernetes Secret.
53+
54+
## HTTP interface
55+
56+
<OpenAPISpecRenderer url={useBaseUrl('/spec/cluster-manager.yaml')}
57+
text={'the Cluster Manager component'}/>
58+
59+
## Well-Known UUIDs
60+
61+
These well-known UUIDs are part of the core framework and all **MUST**
62+
to be registered with the Configuration Store component under the
63+
appropriate classes.
64+
65+
### Configuration and discovery
66+
67+
<WellKnownUUID type='Service Function' name='Cluster Manager'
68+
uuid='2706aa43-a826-441e-9cec-cd3d4ce623c2'
69+
description='The Service UUID used for locating the Cluster Manager endpoints'/>
70+
71+
<WellKnownUUID type="Class" name="Edge cluster"
72+
uuid="f24d354d-abc1-4e32-98e1-0667b3e40b61"
73+
description="Config Store Class used for edge cluster UUIDs"/>
74+
75+
<WellKnownUUID type="Application" name="Edge cluster configuration"
76+
uuid="bdb13634-0b3d-4e38-a065-9d88c12ee78d"
77+
description="Requested configuration for an edge cluster"/>
78+
79+
<WellKnownUUID type="Application" name="Edge cluster setup status"
80+
uuid="747a62c9-1b66-4a2e-8dd9-0b70a91b6b75"
81+
description="Private status entry used by the Cluster Manager"/>

‎docs/framework-components/core-components/commands.mdx renamed to ‎docs/framework-components/central/commands.mdx

Lines changed: 6 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,22 @@
11
---
2-
sidebar_position: 6
2+
sidebar_position: 5
33
---
44

55
import useBaseUrl from "@docusaurus/useBaseUrl";
6-
import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";import {OpenSourceExample} from "../../../src/components/OpenSourceExample";
6+
import { CentralCluster } from "../../../src/components/Clusters";
7+
import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";
8+
import {OpenSourceExample} from "../../../src/components/OpenSourceExample";
79

810
# Commands
911

10-
export const ComponentOverview = () => (
11-
<div className="mb-10 mx-auto text-center w-full flex justify-center">
12-
<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>
13-
<div className="flex flex-col">
14-
<div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-brand h-[3vw] opacity-40"></div>
15-
<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>
16-
</div>
17-
<div className="grid grid-cols-5 gap-2">
18-
<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>
19-
<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>
20-
<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>
21-
<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>
22-
<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>
23-
<div className="p-4 bg-brand-80 dark:bg-brand-40 text-white dark:text-brand flex items-center justify-center">Commands</div>
24-
<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>
25-
<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>
26-
<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>
27-
</div>
28-
</div>
29-
);
30-
3112
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.
3213

3314

3415
<OpenSourceExample buttonText={'ACS Commands Component'} repoUrl={'https://github.com/AMRC-FactoryPlus/acs-cmdesc'}></OpenSourceExample>
3516

3617
## Overview
3718

38-
<ComponentOverview></ComponentOverview>
19+
<CentralCluster hilite="commands"/>
3920

4021
## MQTT Interface
4122

@@ -229,4 +210,4 @@ The `type` is represented as one of the names used for metric types in the Spark
229210
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
230211
Sparkplug Devices intended as Commands targets.
231212

232-
This application is documented more fully in the [Configuration Store](/docs/framework-components/core-components/configuration-store#applications) documentation.
213+
This application is documented more fully in the [Configuration Store](/docs/framework-components/central/configuration-store#applications) documentation.

‎docs/framework-components/core-components/configuration-store.mdx renamed to ‎docs/framework-components/central/configuration-store.mdx

Lines changed: 6 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,40 +3,21 @@ sidebar_position: 4
33
---
44

55
import useBaseUrl from "@docusaurus/useBaseUrl";
6-
import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";import {OpenSourceExample} from "../../../src/components/OpenSourceExample";
6+
import { CentralCluster } from "../../../src/components/Clusters";
7+
import OpenAPISpecRenderer from "../../../src/components/OpenAPISpecRenderer";
8+
import {OpenSourceExample} from "../../../src/components/OpenSourceExample";
79

810
# Configuration Store
911

10-
export const ComponentOverview = () => (
11-
<div className="mb-10 mx-auto text-center w-full flex justify-center">
12-
<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>
13-
<div className="flex flex-col">
14-
<div className="p-4 bg-brand-20 dark:bg-brand-90 dark:text-brand h-[3vw] opacity-40"></div>
15-
<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>
16-
</div>
17-
<div className="grid grid-cols-5 gap-2">
18-
<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>
19-
<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>
20-
<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>
21-
<div className="p-4 bg-brand-80 dark:bg-brand-40 text-white dark:text-brand flex items-center justify-center">Configuration Store</div>
22-
<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>
23-
<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>
24-
<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>
25-
<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>
26-
<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>
27-
</div>
28-
</div>
29-
);
30-
3112
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.
3213

3314
<OpenSourceExample buttonText={'ACS Configuration Store Component'} repoUrl={'https://github.com/AMRC-FactoryPlus/acs-configdb'}></OpenSourceExample>
3415

3516
## Overview
3617

37-
<ComponentOverview></ComponentOverview>
18+
<CentralCluster hilite="configuration-store"/>
3819

39-
Configuration Store component entries are saved as JSON documents.
20+
Config Store component entries are saved as JSON documents.
4021

4122
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.
4223

@@ -45,7 +26,7 @@ The fundamental design concept for the Configuration Store component stipulates
4526
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`.
4627

4728
- **Applications**, as defined above, can store global defaults using their respective `Application_UUID`.
48-
- **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`.
29+
- **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`.
4930
- **Schemas** pertain to Factory+ schemas as outlined in the [Schema specification](/docs/schemas) and are identified by the schema's `Schema_UUID`.
5031

5132
## Application Schema Requirements

0 commit comments

Comments
 (0)