Configuration Store
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.
ACS Configuration Store Component
Overview
Configuration 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.
The fundamental design concept for the Configuration Store component stipulates that any entry saved under a specific Application_UUID MUST adhere to a schema, ensuring that consuming applications can effectively utilise it. Additionally, it is feasible to store these schemas themselves directly in the component, enabling validation and allowing a universal editing application to generate accurate configuration entries.
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 for information on locating a device's
Instance_UUID. - Schemas pertain to Factory+ schemas as outlined in the Schema specification and are identified by the schema's
Schema_UUID.
Application Schema Requirements
- Application schemas MUST use the 2020-12 draft version of JSON schema, i.e. the schema itself should have the
"$schema": "https://json-schema.org/draft/2020-12/schema"top-level property. - Schemas MUST include an
$idfield with the valueurn:uuid:{Application_UUID}, (e.g."$id": "urn:uuid:64a8bfa9-7772-45c4-9d1a-9e6290690957"). - Schemas should also include a
titleanddescriptionfor the whole schema, and adescriptionfor every property, as this information may be used in future to build an editing interface for the config information. - It is advisable to include
"additionalProperties": falseon object definitions otherwise the schema will allow random extra properties. This will make extending the schema in the future without invalidating existing data much harder.
MQTT Interface
To conform with the Component Specification, the Directory component MUST publish the following metrics:
| Metric | Type | A config entry has changed for: |
|---|---|---|
| Application | UUID | An application |
| Device | UUID | A device |
| Schema | UUID | A schema |
The Application metric will have A published to it for updates to both /v1/app/A/... and /v1/app/.../app/A, i.e. both updates to this app's configuration and updates to configuration about this app.
Note that while it is currently the case that an update to /v1/app/A/device/D will publish A to Application and D to Device in the same Sparkplug packet, this is explicitly not guaranteed. Sparkplug does not allow assumptions to be made about any relationship between metric values published in the same packet.
HTTP Interface
Except for the /ping endpoint, all endpoints for the Configuration Store component are located under the /v1 path to allow for forwards compatibility.
Authentication
All requests MUST supply HTTP authentication; the following mechanisms are supported:
| Mechanism | Authentication info required |
|---|---|
| Negotiate | A Kerberos GSSAPI token. |
| Basic | Username and password for a password-based Kerberos principal. |
| Bearer | A token from the /token endpoint. |
Specification
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.
Identity
Permission Groups
This group must be set up in the Authorisation Component to contain all the permissions below.
Permissions
This permission grants the right to read config entries. The target specifies an Application; all config entries for that Application can be read.
This permission grants the right to write config entries for a given application. Entries can be created, but only against objects which are already registered with the Configuration Store.
This permission allows the PUT /v1/app/{app}/config-schema endpoint to be used. This endpoint sets the JSON schema against which an Application's entries are validated.
This permission allows objects to be created. The object must be created in a class which has been granted as target of the permission; or the permission may be granted wildcard to allow any class.
This permission also grants the right to list the classes in question.
This permission does not allow objects to be deleted; that is destructive and is not normally appropriate, so it has a separate permission.
This permission grants the right to delete an object. It should be granted sparingly; normally once a UUID has been allocated to a given object it is worth keeping a permanent record of that fact.
The target of the permission must be the object to be deleted (or an Authorisation Component group containing that object).
Class Definitions
Class definitions are the core building blocks of the Configuration Store component. Every object known to the Store belongs to exactly one class; there is no inheritance. The class indicates what kind of real-world object the UUID represents; often this indicates to applications and services consuming the UUID what operations can be performed on that object.
Some classes of UUID are used internally by the Configuration Store. Some others are also defined here as they are generally useful across all components.
The class definition for the Class Definition class itself. All other class definitions belong to this class.
It is useful to be able to register configuration against this UUID, even though it doesn't represent any real-world object. As such it is defined as a class definition.
Objects must NEVER be created using this class.
UUIDs registered with this class can be used in the /app/{app} endpoints to store config information. A UUID of this class represents a particular schema of config information.
These UUIDs represent the Factory+ Components. Component implementations publish these UUIDs to indicate that they conform to a particular component specification.
UUIDs of this class represent metric schemas defined under the Factory+ Data Schemas specification.
Applications
These entries are created by the POST /v1/object endpoint. They cannot be created directly, as an entry for the object must exist before the /app/{app}/object endpoint can be used.
Entries have a single property, class, indicating the class of the object.
These are intended for display to human users in user interfaces to help the user understand what object is being referred to and should be brief (no more than a few words).
Entries MUST have at least the following properties (this is likely to be extended in the future).
| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | A name for the object |
location | string | No | The physical location of the object |
photo | string | No | A base64-encoded photo |
contact | array | No | An array of contact information |
The contact property contains contact information for the people responsible for the object. The array contains objects with these properties:
| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name of a responsible person |
email | string | Yes | Their email address |
Where an object has a pre-defined Sparkplug address, entries with this application can be used to allow this address to be looked up. Under the current architecture Sparkplug Nodes have fixed addresses and require entries of this type. Sparkplug Devices are discovered via the Directory and do not normally need these entries.
Entries of this type are used by the MQTT component to define ACLs, and by the Commands component to authenticate escalation requests.
Entries have the following properties:
| Property | Type | Required | Description |
|---|---|---|---|
group_id | string | Yes | The Sparkplug Group ID |
node_id | string | Yes | The Sparkplug Node ID |
device_id | string | No | The Sparkplug Device ID |
Examples
Global Application Configuration
The global application configuration can be managed via the /v1/app/{Application_UUID}/config endpoint. For compatibility reasons. This accepts GET, PUT and DELETE requests and is exactly equivalent to /v1/app/{Application_UUID}/app/{Application_UUID}.
Managing Applications
Before configuration can be stored for a particular application, the Application_UUID MUST be registered with the service. The following endpoints are available for this purpose.
Get All Applications
// Returns an array listing all the known app UUIDs.
GET /v1/app
Registering and Updating Applications
// Registers a new application or updates an existing registration.
POST /v1/app
When making a POST request to register a new application the body should be an object with the following properties:
| Property | Description |
|---|---|
uuid | The Application_UUID. |
name | A human-readable name for the application. |
Get Application Information
// Retrieves information about a particular application.
// e.g. GET /v1/app/123-456
GET /v1/app/{Application_UUID}
Delete Applications
There is currently no endpoint to delete applications. This is potentially a very destructive operation as it would need to delete all configuration entries stored against that Application_UUID.
Application Configuration Schemas
Getting Schemas
The schema used by an application to store its configuration entries can be accessed by making a request to the following endpoint. This request will return 404 if no configuration schema has been registered for a particular application.
// Get the schema for an application's configuration
// e.g. GET /v1/app/123-456/config-schema
GET /v1/app/{Application_UUID}/config-schema
Creating Schemas
This request will only accept a new schema if all configuration entries currently in the database for that application validate against the new schema. If this validation step fails the endpoint will return a status code of 409 Conflict, with a JSON array body listing all the Instance_UUIDs for which validation failed. This will include the Application_UUID itself if validation failed for the application's global configuration.
// Create a new schema for an application's configuration
// e.g. PUT /v1/app/123-456/config-schema
PUT /v1/app/{Application_UUID}/config-schema
Per-Object Configuration
The following endpoints for per-object configuration contain a component identifying the kind of object being referred to. This component should be
| Object kind | Component |
|---|---|
| Application | app |
| Device | device |
| Schema | schema |
Getting Configuration for All Objects
// Get a list of all the objects which have configuration entries for a particular application
// e.g. GET /v1/app/123-456/device
GET /v1/app/{Application_UUID}/{object_type}
A request to the above endpoint would return an array of object UUIDs.
Managing Configuration for a Specific Object
// Get the configuration for the specified object
// e.g. GET /v1/app/123-456/device/abc-def
GET /v1/app/{Application_UUID}/{object_type}/{object_uuid}
// Create a new configuration for the specified object
// e.g. PUT /v1/app/123-456/device/abc-def
PUT /v1/app/{Application_UUID}/{object_type}/{object_uuid}
// Delete the configuration for the specified object
// e.g. DELETE /v1/app/123-456/device/abc-def
DELETE /v1/app/{Application_UUID}/{object_type}/{object_uuid}
If a schema is registered for the application and an entry supplied does not validate then a 403 status code is returned.