Add deployment blueprint
This commit is contained in:
znetsixe
270
architecture/deployment-blueprint.md
Normal file
270
architecture/deployment-blueprint.md
Normal file
@@ -0,0 +1,270 @@
|
|||||||
|
# EVOLV Deployment Blueprint
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This document turns the current EVOLV architecture into a concrete deployment model.
|
||||||
|
|
||||||
|
It focuses on:
|
||||||
|
|
||||||
|
- target infrastructure layout
|
||||||
|
- container/service topology
|
||||||
|
- environment and secret boundaries
|
||||||
|
- rollout order from edge to site to central
|
||||||
|
|
||||||
|
It is the local source document behind the wiki deployment pages.
|
||||||
|
|
||||||
|
## 1. Deployment Principles
|
||||||
|
|
||||||
|
- edge-first operation: plant logic must continue when central is unavailable
|
||||||
|
- site mediation: site services protect field systems and absorb plant-specific complexity
|
||||||
|
- central governance: external APIs, analytics, IAM, CI/CD, and shared dashboards terminate centrally
|
||||||
|
- layered telemetry: InfluxDB exists where operationally justified at edge, site, and central
|
||||||
|
- configuration authority: `tagcodering` should become the source of truth for configuration
|
||||||
|
- secrets hygiene: tracked manifests contain variables only; secrets live in server-side env or secret stores
|
||||||
|
|
||||||
|
## 2. Layered Deployment Model
|
||||||
|
|
||||||
|
### 2.1 Edge node
|
||||||
|
|
||||||
|
Purpose:
|
||||||
|
|
||||||
|
- interface with PLCs and field assets
|
||||||
|
- execute local Node-RED logic
|
||||||
|
- retain local telemetry for resilience and digital-twin use cases
|
||||||
|
|
||||||
|
Recommended services:
|
||||||
|
|
||||||
|
- `evolv-edge-nodered`
|
||||||
|
- `evolv-edge-influxdb`
|
||||||
|
- optional `evolv-edge-grafana`
|
||||||
|
- optional `evolv-edge-broker`
|
||||||
|
|
||||||
|
Should not host:
|
||||||
|
|
||||||
|
- public API ingress
|
||||||
|
- central IAM
|
||||||
|
- source control or CI/CD
|
||||||
|
|
||||||
|
### 2.2 Site node
|
||||||
|
|
||||||
|
Purpose:
|
||||||
|
|
||||||
|
- aggregate one or more edge nodes
|
||||||
|
- host plant-local dashboards and engineering visibility
|
||||||
|
- mediate traffic between edge and central
|
||||||
|
|
||||||
|
Recommended services:
|
||||||
|
|
||||||
|
- `evolv-site-nodered` or `coresync-site`
|
||||||
|
- `evolv-site-influxdb`
|
||||||
|
- `evolv-site-grafana`
|
||||||
|
- optional `evolv-site-broker`
|
||||||
|
|
||||||
|
### 2.3 Central platform
|
||||||
|
|
||||||
|
Purpose:
|
||||||
|
|
||||||
|
- fleet-wide analytics
|
||||||
|
- API and integration ingress
|
||||||
|
- engineering lifecycle and releases
|
||||||
|
- identity and governance
|
||||||
|
|
||||||
|
Recommended services:
|
||||||
|
|
||||||
|
- reverse proxy / ingress
|
||||||
|
- API gateway
|
||||||
|
- IAM
|
||||||
|
- central InfluxDB
|
||||||
|
- central Grafana
|
||||||
|
- Gitea
|
||||||
|
- CI/CD runner/controller
|
||||||
|
- optional broker for asynchronous site/central workflows
|
||||||
|
- configuration services over `tagcodering`
|
||||||
|
|
||||||
|
## 3. Target Container Topology
|
||||||
|
|
||||||
|
### 3.1 Edge host
|
||||||
|
|
||||||
|
Minimum viable edge stack:
|
||||||
|
|
||||||
|
```text
|
||||||
|
edge-host-01
|
||||||
|
- Node-RED
|
||||||
|
- InfluxDB
|
||||||
|
- optional Grafana
|
||||||
|
```
|
||||||
|
|
||||||
|
Preferred production edge stack:
|
||||||
|
|
||||||
|
```text
|
||||||
|
edge-host-01
|
||||||
|
- Node-RED
|
||||||
|
- InfluxDB
|
||||||
|
- local health/export service
|
||||||
|
- optional local broker
|
||||||
|
- optional local dashboard service
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 Site host
|
||||||
|
|
||||||
|
Minimum viable site stack:
|
||||||
|
|
||||||
|
```text
|
||||||
|
site-host-01
|
||||||
|
- Site Node-RED / CoreSync
|
||||||
|
- Site InfluxDB
|
||||||
|
- Site Grafana
|
||||||
|
```
|
||||||
|
|
||||||
|
Preferred production site stack:
|
||||||
|
|
||||||
|
```text
|
||||||
|
site-host-01
|
||||||
|
- Site Node-RED / CoreSync
|
||||||
|
- Site InfluxDB
|
||||||
|
- Site Grafana
|
||||||
|
- API relay / sync service
|
||||||
|
- optional site broker
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 Central host group
|
||||||
|
|
||||||
|
Central should not be one giant undifferentiated host forever. It should trend toward at least these responsibility groups:
|
||||||
|
|
||||||
|
```text
|
||||||
|
central-ingress
|
||||||
|
- reverse proxy
|
||||||
|
- API gateway
|
||||||
|
- IAM
|
||||||
|
|
||||||
|
central-observability
|
||||||
|
- central InfluxDB
|
||||||
|
- Grafana
|
||||||
|
|
||||||
|
central-engineering
|
||||||
|
- Gitea
|
||||||
|
- CI/CD
|
||||||
|
- deployment orchestration
|
||||||
|
|
||||||
|
central-config
|
||||||
|
- tagcodering-backed config services
|
||||||
|
```
|
||||||
|
|
||||||
|
For early rollout these may be colocated, but the responsibility split should remain clear.
|
||||||
|
|
||||||
|
## 4. Compose Strategy
|
||||||
|
|
||||||
|
The current repository shows:
|
||||||
|
|
||||||
|
- `docker-compose.yml` as a development stack
|
||||||
|
- `temp/cloud.yml` as a broad central-stack example
|
||||||
|
|
||||||
|
For production, EVOLV should not rely on one flat compose file for every layer.
|
||||||
|
|
||||||
|
Recommended split:
|
||||||
|
|
||||||
|
- `compose.edge.yml`
|
||||||
|
- `compose.site.yml`
|
||||||
|
- `compose.central.yml`
|
||||||
|
- optional overlay files for site-specific differences
|
||||||
|
|
||||||
|
Benefits:
|
||||||
|
|
||||||
|
- clearer ownership per layer
|
||||||
|
- smaller blast radius during updates
|
||||||
|
- easier secret and env separation
|
||||||
|
- easier rollout per site
|
||||||
|
|
||||||
|
## 5. Environment And Secrets Strategy
|
||||||
|
|
||||||
|
### 5.1 Current baseline
|
||||||
|
|
||||||
|
`temp/cloud.yml` now uses environment variables instead of inline credentials. That is the minimum acceptable baseline.
|
||||||
|
|
||||||
|
### 5.2 Recommended production rule
|
||||||
|
|
||||||
|
- tracked compose files contain `${VARIABLE}` placeholders only
|
||||||
|
- real secrets live in server-local `.env` files or a managed secret store
|
||||||
|
- no shared default production passwords in git
|
||||||
|
- separate env files per layer and per environment
|
||||||
|
|
||||||
|
Suggested structure:
|
||||||
|
|
||||||
|
```text
|
||||||
|
/opt/evolv/
|
||||||
|
compose.edge.yml
|
||||||
|
compose.site.yml
|
||||||
|
compose.central.yml
|
||||||
|
env/
|
||||||
|
edge.env
|
||||||
|
site.env
|
||||||
|
central.env
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Recommended Network Flow
|
||||||
|
|
||||||
|
### 6.1 Northbound
|
||||||
|
|
||||||
|
- edge publishes or syncs upward to site
|
||||||
|
- site aggregates and forwards selected data to central
|
||||||
|
- central exposes APIs and dashboards to approved consumers
|
||||||
|
|
||||||
|
### 6.2 Southbound
|
||||||
|
|
||||||
|
- central issues advice, approved config, or mediated requests
|
||||||
|
- site validates and relays to edge where appropriate
|
||||||
|
- edge remains the execution point near PLCs
|
||||||
|
|
||||||
|
### 6.3 Forbidden direct path
|
||||||
|
|
||||||
|
- enterprise or internet clients should not directly query PLC-connected edge runtimes
|
||||||
|
|
||||||
|
## 7. Rollout Order
|
||||||
|
|
||||||
|
### Phase 1: Edge baseline
|
||||||
|
|
||||||
|
- deploy edge Node-RED
|
||||||
|
- deploy local InfluxDB
|
||||||
|
- validate PLC connectivity
|
||||||
|
- validate local telemetry and resilience
|
||||||
|
|
||||||
|
### Phase 2: Site mediation
|
||||||
|
|
||||||
|
- deploy site Node-RED / CoreSync
|
||||||
|
- connect one or more edge nodes
|
||||||
|
- validate site-local dashboards and outage behavior
|
||||||
|
|
||||||
|
### Phase 3: Central services
|
||||||
|
|
||||||
|
- deploy ingress, IAM, API, Grafana, central InfluxDB
|
||||||
|
- deploy Gitea and CI/CD services
|
||||||
|
- validate controlled northbound access
|
||||||
|
|
||||||
|
### Phase 4: Configuration backbone
|
||||||
|
|
||||||
|
- connect runtime layers to `tagcodering`
|
||||||
|
- reduce config duplication in flows
|
||||||
|
- formalize config promotion and rollback
|
||||||
|
|
||||||
|
### Phase 5: Smart telemetry policy
|
||||||
|
|
||||||
|
- classify signals
|
||||||
|
- define reconstruction rules
|
||||||
|
- define authoritative layer per horizon
|
||||||
|
- validate analytics and auditability
|
||||||
|
|
||||||
|
## 8. Immediate Technical Recommendations
|
||||||
|
|
||||||
|
- treat `docker/settings.js` as development-only and create hardened production settings separately
|
||||||
|
- split deployment manifests by layer
|
||||||
|
- define env files per layer and environment
|
||||||
|
- formalize healthchecks and backup procedures for every persistent service
|
||||||
|
- define whether broker usage is required at edge, site, central, or only selectively
|
||||||
|
|
||||||
|
## 9. Next Technical Work Items
|
||||||
|
|
||||||
|
1. create draft `compose.edge.yml`, `compose.site.yml`, and `compose.central.yml`
|
||||||
|
2. define server directory layout and env-file conventions
|
||||||
|
3. define production Node-RED settings profile
|
||||||
|
4. define site-to-central sync path
|
||||||
|
5. define deployment and rollback runbook
|
||||||
Reference in New Issue
Block a user