diff --git a/docs/reference/release-notes.md b/docs/reference/release-notes.md index 24cc2c06a..f44339c3e 100644 --- a/docs/reference/release-notes.md +++ b/docs/reference/release-notes.md @@ -8,6 +8,183 @@ chronological order. These changes have not been released yet, but are likely to appear in the next release. +## v6.0.0 + +This is a major release. It changes the Sparkplug timestamp format, the +way users log in to Grafana, and two ConfigDB permissions. None of these +are backwards compatible. Please read this whole section before +upgrading a production installation. + +Note that v4 and v5 were not documented here; this section describes the +changes from v5.1.0. + +### Nanosecond timestamps: upgrade central services before edge agents + +Sparkplug payload and metric timestamps now hold **nanoseconds** since +the epoch, in the same `uint64` field that previously held milliseconds. +The UNS JSON `timestamp` field is likewise now an ISO-8601 string with +nanosecond precision, for example `2026-05-28T15:46:56.100923659Z` +rather than `2026-05-28T15:46:56.100Z`. + +Components from this release read a timestamp below 1e15 as milliseconds +and convert it, so a v6 central service can consume data from a v5 edge +agent. **The reverse is not true.** A v5 historian reading from a v6 +edge agent will interpret a nanosecond value as milliseconds and store +points dated tens of millions of years in the future. Upgrade the +central services first, then the edge agents. + +Two further consequences: + +- The Sparkplug B specification defines this field as milliseconds. Any + external, non-ACS consumer that reads ACS Sparkplug payloads directly + will misinterpret the new values, and any consumer of the UNS topics + with a strict RFC 3339 parser may reject the extra digits of + precision. +- Existing InfluxDB data is unaffected and needs no migration. Both + historians already wrote at nanosecond precision, so stored timestamps + and measurement names are unchanged. + +### Grafana now authenticates through Keycloak + +Previously Grafana sat behind a Traefik `basic-auth` middleware and +trusted a proxied header (`auth.proxy`). This release deploys Keycloak +as an OIDC provider and Grafana authenticates against it. The +`grafana.grafana.ini.auth.proxy` values have been removed, and Grafana's +own login form is hidden: users sign in via a "Factory+" SSO button. + +Keycloak itself validates credentials against Kerberos, and Kerberos +authentication is otherwise unchanged. Edge agents, the Manager and the +other central services continue to authenticate exactly as they did. + +On upgrade you must: + +- Create a DNS record for the new `openid.` host and ensure + your TLS certificate covers it. +- Grant Grafana roles through Factory+ permissions. Roles are no longer + held in Grafana. Add principals to the groups listed under + `serviceSetup.config.grafanaPermissions`; anyone without a grant + becomes a Viewer, and revoking a grant demotes the user at their next + login. The maximum role is now Admin, as Grafana Admin is no longer + assigned. +- Check that your existing Grafana users can still reach their accounts. + Dashboards and the Grafana database are preserved across the upgrade, + but federated logins now arrive with the Kerberos UPN as their + username. Where that differs from the username a v5 proxy login + created, the user may be given a fresh Viewer account instead of + reclaiming the old one. + +The Keycloak deployment uses the custom `acs-keycloak` image, which has +the Factory+ storage provider built in. Stock upstream Keycloak will not +work. The Keycloak admin password, the client secrets and the Keycloak +database are all created automatically; there is no manual realm or +client configuration to do. + +Setting `openid.enabled` to `false` will skip Keycloak, but Grafana then +has no interactive login other than the local emergency admin account, +which remains reachable at `/login?disableLoginForm=false`. + +### Machine-to-machine OIDC clients + +Clients declared under `serviceSetup.config.openidClients` may now set +`serviceAccountsEnabled: true`, which turns on the OAuth +client-credentials grant so an unattended consumer, such as a display +wall or a scheduled job, can exchange its generated client secret for a +token without a human login. Such a client should normally also set +`standardFlowEnabled: false`, as it has no browser session to redirect. +Keycloak only supports service accounts on confidential clients, so the +flag is ignored on a client marked `publicClient`. + +This is off unless asked for, and existing clients are unaffected. + +### Two new services are exposed by default + +`i3x` and `data-access` are both enabled by default, and each publishes +an external host: `i3x.` and `data-access.`. +Add DNS records and extend your TLS certificate to cover them, or set +`i3x.enabled` or `dataAccess.enabled` to `false`. The i3X service +depends on Keycloak, so do not disable `openid` while leaving `i3x` +enabled. + +### ConfigDB permission changes + +Adding a subclass relationship now requires the `WriteSuperclasses` +permission on the target class, where previously `ReadSubclasses` was +enough. The accounts shipped with ACS are updated automatically, but +**any local principal that creates subclasses must be granted the new +permission**, otherwise those writes will start returning 403. + +The Files service now also requires `ReadMembers` on the file class, +without which file operations fail with permission errors. + +Both grants are applied by the service-setup Job, which runs +automatically as part of `helm upgrade`. + +### ConfigDB version 1 dumps are no longer accepted + +Support for the version 1 dump format has been removed. Any dumps you +maintain outside this repository must be converted to version 2. + +### Service registration has moved into the Helm chart + +Service URLs used to be registered from a fixed dump baked into the +service-setup image. They are now generated by the chart and gated on +each service's `enabled` flag, so only the services you actually deploy +are advertised in the Directory. No change to your values file is +needed, and no stale registrations need clearing out. The Directory +database picks up a new schema version automatically on startup, which +makes the `device` column of a service advertisement optional. + +### The ISA-95 hierarchy is now a controlled vocabulary + +The five ISA-95 levels (Enterprise, Site, Area, Work Centre, Work Unit) +are no longer free-text fields on a device. They are selected from a +vocabulary of ConfigDB objects, which prevents the inconsistent spelling +of site and area names that free text allowed. + +The vocabulary is managed from the new **ISA-95** page in the Manager, +where hierarchy nodes can be created, renamed, given alternative names +(aliases) and pruned. A node cannot be deleted while it still has +children, so a hierarchy is dismantled from the bottom up rather than +leaving orphaned nodes behind. + +Nothing seeds the vocabulary automatically: the bundled dump creates +only the five level classes and the vocabulary application. Until nodes +exist, the hierarchy dropdowns on a device are empty and the hierarchy +cannot be set. + +**If you are upgrading an installation that already has hierarchy values +typed against its devices,** use "Import from Devices" on the ISA-95 +page rather than retyping them. This reads the values already saved on +every device, shows you what it proposes to create, and builds the +vocabulary to match. Names that differ only in case or spelling from an +existing node are attached to that node as aliases, so a device keeps +resolving against the vocabulary without being edited. Devices are never +modified by the import. Values that sit below a missing level (an Area +on a device with no Site, say) cannot be placed in the tree; they are +reported and left alone. + +The import is deliberately a manual action rather than something that +runs on upgrade. Nodes are derived from device values, which the import +does not rewrite, so a migration that ran automatically would recreate +any node you had pruned every time the chart was upgraded. Run it when +you choose to, prune what you do not want, and the result stays as you +left it. You can run it again at any time to pick up devices added +later. + +CSV import ignores the ISA-95 columns for the same reason the metric +tree hides them. They are still present in an exported CSV, but editing +them and re-importing will not change the hierarchy; use the ISA-95 +Hierarchy panel on the device, or the ISA-95 page, instead. + +### MetaDB is present but disabled + +This release includes the first parts of the MetaDB, an RDF-backed +reimplementation of the ConfigDB. It ships disabled and its integration +is not yet complete, so it should not be enabled on a production +installation. Turning on `metadb.asConfigDB` repoints the Directory's +ConfigDB advertisement at the MetaDB and requires `configdb.enabled` to +be `false`; there is no migration of existing ConfigDB content into it. + ## v3.4.0 ### Unified Namespace & Historian