9c6e3c2e56
Adds `debug snapshot --id <int>` to query a running instance's current attribute values and alarm states without the subscribe/stream overhead of the debug view. Routes through ManagementActor → CommunicationService → site DeploymentManager → InstanceActor using the existing remote query pattern.
182 lines
11 KiB
Markdown
182 lines
11 KiB
Markdown
# Component: Management Service
|
|
|
|
## Purpose
|
|
|
|
The Management Service is an Akka.NET actor on the central cluster that provides programmatic access to all administrative operations. It exposes the same capabilities as the Central UI but through an actor-based interface, enabling the CLI (and potentially other tooling) to interact with the system without going through the web UI. The ManagementActor registers with ClusterClientReceptionist so that external processes can reach it via ClusterClient without joining the cluster.
|
|
|
|
## Location
|
|
|
|
Central cluster only (active node). The ManagementActor runs as a cluster singleton on the central cluster.
|
|
|
|
`src/ScadaLink.ManagementService/`
|
|
|
|
## Responsibilities
|
|
|
|
- Provide an actor-based interface to all administrative operations available in the Central UI.
|
|
- Register with Akka.NET ClusterClientReceptionist so external tools (CLI) can discover and communicate with it via ClusterClient.
|
|
- Validate and authorize all incoming commands using the authenticated user identity carried in message envelopes.
|
|
- Delegate to the appropriate services and repositories for each operation.
|
|
- Return structured response messages for all commands and queries.
|
|
- Failover: The ManagementActor is available on the active central node and fails over with it. ClusterClient handles reconnection transparently.
|
|
|
|
## Key Classes
|
|
|
|
### ManagementActor
|
|
|
|
The central actor that receives and processes all management commands. Registered at a well-known actor path (`/user/management`) and with ClusterClientReceptionist.
|
|
|
|
### Message Contracts
|
|
|
|
All request/response messages are defined in **Commons** under `Messages/Management/`. Messages follow the existing additive-only evolution rules for version compatibility. Every request message includes:
|
|
|
|
- **CorrelationId**: Application-level correlation ID for request/response pairing.
|
|
- **AuthenticatedUser**: The identity and roles of the user issuing the command (username, display name, roles, permitted sites). This is populated by the CLI from the user's authenticated session.
|
|
|
|
## ClusterClientReceptionist Registration
|
|
|
|
The ManagementActor registers itself with `ClusterClientReceptionist` at startup. This allows external processes using `ClusterClient` to send messages to the ManagementActor without joining the Akka.NET cluster as a full member. The receptionist advertises the actor under its well-known path.
|
|
|
|
## Message Groups
|
|
|
|
### Templates
|
|
|
|
- **ListTemplates** / **GetTemplate**: Query template definitions.
|
|
- **CreateTemplate** / **UpdateTemplate** / **DeleteTemplate**: Manage templates.
|
|
- **ValidateTemplate**: Run on-demand pre-deployment validation (flattening, naming collisions, script compilation).
|
|
- **GetTemplateDiff**: Compare deployed vs. template-derived configuration for an instance.
|
|
|
|
### Template Members
|
|
|
|
- **AddTemplateAttribute** / **UpdateTemplateAttribute** / **DeleteTemplateAttribute**: Manage attributes on a template.
|
|
- **AddTemplateAlarm** / **UpdateTemplateAlarm** / **DeleteTemplateAlarm**: Manage alarm definitions on a template.
|
|
- **AddTemplateScript** / **UpdateTemplateScript** / **DeleteTemplateScript**: Manage scripts on a template.
|
|
- **AddTemplateComposition** / **DeleteTemplateComposition**: Manage feature module compositions on a template.
|
|
|
|
### Instances
|
|
|
|
- **ListInstances** / **GetInstance**: Query instances, with filtering by site and area.
|
|
- **CreateInstance**: Create a new instance from a template.
|
|
- **UpdateInstanceOverrides**: Set attribute overrides on an instance.
|
|
- **SetInstanceBindings** / **BindDataConnections**: Bind data connections to instance attributes.
|
|
- **AssignArea**: Assign an instance to an area.
|
|
- **EnableInstance** / **DisableInstance** / **DeleteInstance**: Instance lifecycle commands.
|
|
|
|
### Sites
|
|
|
|
- **ListSites** / **GetSite**: Query site definitions.
|
|
- **CreateSite** / **UpdateSite** / **DeleteSite**: Manage site definitions.
|
|
- **ListAreas** / **CreateArea** / **UpdateArea** / **DeleteArea**: Manage area hierarchies per site.
|
|
|
|
### Data Connections
|
|
|
|
- **ListDataConnections** / **GetDataConnection**: Query data connection definitions.
|
|
- **CreateDataConnection** / **UpdateDataConnection** / **DeleteDataConnection**: Manage data connection definitions.
|
|
- **AssignDataConnectionToSite** / **UnassignDataConnectionFromSite**: Manage site assignments.
|
|
|
|
### Deployments
|
|
|
|
- **DeployInstance**: Deploy configuration to a specific instance (includes pre-deployment validation).
|
|
- **DeployArtifacts**: Deploy system-wide artifacts (shared scripts, external system definitions, DB connections, data connections, notification lists, SMTP config) to all sites or a specific site.
|
|
- **GetDeploymentStatus**: Query deployment status.
|
|
|
|
### External Systems
|
|
|
|
- **ListExternalSystems** / **GetExternalSystem**: Query external system definitions.
|
|
- **CreateExternalSystem** / **UpdateExternalSystem** / **DeleteExternalSystem**: Manage external system definitions.
|
|
|
|
### Notifications
|
|
|
|
- **ListNotificationLists** / **GetNotificationList**: Query notification lists.
|
|
- **CreateNotificationList** / **UpdateNotificationList** / **DeleteNotificationList**: Manage notification lists and recipients.
|
|
- **GetSmtpConfig** / **UpdateSmtpConfig**: Query and update SMTP configuration.
|
|
|
|
### Security (LDAP & API Keys)
|
|
|
|
- **ListApiKeys** / **CreateApiKey** / **UpdateApiKey** / **EnableApiKey** / **DisableApiKey** / **DeleteApiKey**: Manage API keys.
|
|
- **ListRoleMappings** / **CreateRoleMapping** / **UpdateRoleMapping** / **DeleteRoleMapping**: Manage LDAP group-to-role mappings.
|
|
- **ListScopeRules** / **AddScopeRule** / **DeleteScopeRule**: Manage site scope rules on role mappings.
|
|
|
|
### Audit Log
|
|
|
|
- **QueryAuditLog**: Query audit log entries with filtering by entity type, user, date range, etc.
|
|
|
|
### Shared Scripts
|
|
|
|
- **ListSharedScripts** / **GetSharedScript**: Query shared script definitions.
|
|
- **CreateSharedScript** / **UpdateSharedScript** / **DeleteSharedScript**: Manage shared scripts.
|
|
|
|
### Database Connections
|
|
|
|
- **ListDatabaseConnections** / **GetDatabaseConnection**: Query database connection definitions.
|
|
- **CreateDatabaseConnection** / **UpdateDatabaseConnection** / **DeleteDatabaseConnection**: Manage database connections.
|
|
|
|
### Inbound API Methods
|
|
|
|
- **ListApiMethods** / **GetApiMethod**: Query inbound API method definitions.
|
|
- **CreateApiMethod** / **UpdateApiMethod** / **DeleteApiMethod**: Manage inbound API methods.
|
|
|
|
### Health
|
|
|
|
- **GetHealthSummary**: Query current health status of all sites.
|
|
- **GetSiteHealth**: Query detailed health for a specific site.
|
|
|
|
### Remote Queries
|
|
|
|
- **QuerySiteEventLog**: Query site event log entries from a remote site (routed via communication layer). Supports date range, keyword search, and pagination.
|
|
- **QueryParkedMessages**: Query parked (dead-letter) messages at a remote site (routed via communication layer). Supports pagination.
|
|
- **DebugSnapshot**: Request a one-shot snapshot of attribute values and alarm states for a running instance. Resolves the instance's site from the config DB and routes via the communication layer. Uses 30s `QueryTimeout`.
|
|
|
|
## Authorization
|
|
|
|
Every incoming message carries the authenticated user's identity and roles. The ManagementActor enforces the same role-based authorization rules as the Central UI:
|
|
|
|
- **Admin** role required for: site management, area management, API key management, role mapping management, scope rule management, system configuration.
|
|
- **Design** role required for: template authoring (including template member management: attributes, alarms, scripts, compositions), shared scripts, external system definitions, database connection definitions, notification lists, inbound API method definitions.
|
|
- **Deployment** role required for: instance management, deployments, debug view, debug snapshot, parked message queries, site event log queries. Site scoping is enforced for site-scoped Deployment users.
|
|
- **Read-only access** (any authenticated role): health summary, health site, site event log queries, parked message queries.
|
|
|
|
Unauthorized commands receive an `Unauthorized` response message. Failed authorization attempts are not audit logged (consistent with existing behavior).
|
|
|
|
## Service Dependencies (DI)
|
|
|
|
The ManagementActor receives the following services and repositories via DI (injected through the actor's constructor or via a service provider):
|
|
|
|
- `ITemplateEngineRepository` / `TemplateService` — Template operations.
|
|
- `InstanceService` — Instance lifecycle and configuration.
|
|
- `ISiteRepository` — Site definitions and area management.
|
|
- `IDeploymentManagerRepository` / `DeploymentService` — Deployment pipeline operations.
|
|
- `ArtifactDeploymentService` — System-wide artifact deployment.
|
|
- `IExternalSystemRepository` — External system definitions.
|
|
- `INotificationRepository` — Notification lists and SMTP config.
|
|
- `ISecurityRepository` — API keys and LDAP role mappings.
|
|
- `IInboundApiRepository` — Inbound API method definitions.
|
|
- `ISharedScriptRepository` / `SharedScriptService` — Shared script definitions.
|
|
- `IDatabaseConnectionRepository` — Database connection definitions.
|
|
- `ICentralHealthAggregator` — Health status aggregation.
|
|
- `CommunicationService` — Central-site communication for deployment and remote queries.
|
|
|
|
## Configuration
|
|
|
|
| Section | Options Class | Contents |
|
|
|---------|--------------|----------|
|
|
| `ScadaLink:ManagementService` | `ManagementServiceOptions` | (Reserved for future configuration — e.g., command timeout overrides) |
|
|
|
|
## Dependencies
|
|
|
|
- **Commons**: Message contracts (`Messages/Management/`), shared types, repository interfaces.
|
|
- **Configuration Database (MS SQL)**: All queries and mutations go through repositories backed by EF Core.
|
|
- **Configuration Database (via IAuditService)**: All mutating operations are audit logged through the existing transactional audit mechanism.
|
|
- **Communication Layer**: Deployment commands and remote queries (parked messages, event logs) are routed to sites via Communication.
|
|
- **Security & Auth**: Authorization rules are enforced on every command using the authenticated user identity from the message envelope.
|
|
- **Cluster Infrastructure**: ManagementActor runs on the active central node; ClusterClientReceptionist requires cluster membership.
|
|
- **All service components**: The ManagementActor delegates to the same services used by the Central UI — Template Engine, Deployment Manager, etc.
|
|
|
|
## Interactions
|
|
|
|
- **CLI**: The primary consumer. Connects via Akka.NET ClusterClient and sends management messages to the ManagementActor.
|
|
- **Host**: Registers the ManagementActor and ClusterClientReceptionist on central nodes during startup.
|
|
- **Central UI**: Shares the same underlying services and repositories. The ManagementActor and Central UI are parallel interfaces to the same operations.
|
|
- **Communication Layer**: Deployment commands and remote site queries flow through communication actors.
|
|
- **Configuration Database (via IAuditService)**: All configuration changes are audited.
|
|
- **Security & Auth**: The ManagementActor enforces authorization using user identity passed in messages. The CLI is responsible for authenticating the user and including their identity in every request.
|