Skip to content

Document v6.0.0 in the release notes#669

Merged
AlexGodbehere merged 2 commits into
mainfrom
ago/v6-release-notes
Jul 9, 2026
Merged

Document v6.0.0 in the release notes#669
AlexGodbehere merged 2 commits into
mainfrom
ago/v6-release-notes

Conversation

@AlexGodbehere

Copy link
Copy Markdown
Contributor

Document v6.0.0 in the release notes

Summary

docs/reference/release-notes.md had not been touched since v3.4.0, so v4 and v5 were never written up and v6 had nothing at all. This adds a v6.0.0 section covering the changes an operator has to act on when upgrading from v5.1.0, and notes the v4/v5 gap rather than pretending it isn't there.

Why v6 is a major release

Three independently sufficient reasons, documented in that order of importance:

  1. Nanosecond timestamps (Add nanosecond timestamp support #659). The Sparkplug uint64 timestamp field now carries nanoseconds where it carried milliseconds. New code treats values below 1e15 as milliseconds, so a v6 central service reads a v5 edge agent fine. The reverse silently corrupts data: a v5 historian reading a v6 edge agent writes points dated tens of millions of years in the future. This dictates an upgrade order, which the notes spell out. It also makes ACS deliberately non-compliant with the Sparkplug B spec, which matters to any external consumer.
  2. Grafana authentication replaced (OAuth Support #646). auth.proxy and the basic-auth middleware are gone, Keycloak is deployed by default, and Grafana roles now come from Factory+ permission grants.
  3. ConfigDB permissions tightened. Creating a subclass now needs WriteSuperclasses on the target class (Fixed configdb object permission for writing subclasses #638), and Files needs ReadMembers (Fix ACS-Files Permissions #654).

Plus the v1 ConfigDB dump format being removed, and the ISA-95 hierarchy becoming a controlled vocabulary.

Manual upgrade steps documented

  • DNS and TLS for three new external hosts (openid, i3x, data-access are all enabled by default).
  • Grafana role grants via serviceSetup.config.grafanaPermissions, and a warning that v5 proxy-created accounts may not be reclaimed under the new UPN-based usernames.
  • WriteSuperclasses for any local principal that creates subclasses.
  • Converting any out-of-repo v1 dumps.
  • Building the ISA-95 vocabulary, now via "Import from Devices" rather than by hand (ISA-95 hierarchy editor and device import #667).

Also covers serviceAccountsEnabled (#668, opt-in, no action) and records that MetaDB ships disabled and incomplete and should stay that way.

Notes for the reviewer

Every factual claim was checked against the code on main rather than against the PR descriptions. One claim I could not settle and have flagged in the notes as something to test: whether existing Grafana user rows created by v5's proxy auth are reclaimed by the new federated logins, or whether those users land as fresh Viewer accounts. The reclaim machinery exists (oauth_allow_insecure_email_lookup, email_attribute_path: preferred_username) but only fires when the old username matches the Kerberos UPN. Worth testing on staging before tagging, because the failure is quiet.

edge-openprotocol is in the tree and the CI image build but is not in values.yaml and not in the driver list, so it cannot be selected in the Manager. I left it out of the notes; you may want to decide whether it belongs in the v6 changelog at all.

The release notes had not been touched since v3.4.0. Add a v6.0.0
section covering the changes that require an operator to act:
nanosecond Sparkplug timestamps, Grafana moving to Keycloak OIDC, the
two new default-on services and their hosts, the ConfigDB subclass and
Files permission changes, removal of v1 dumps, and the ISA-95 controlled
vocabulary needing to be seeded by hand.

Also notes that MetaDB ships disabled and should stay that way, and that
v4 and v5 were never documented here.
Following #667 and #668, both merged.

The ISA-95 section no longer tells operators to build the vocabulary by
hand. It points at the new ISA-95 page and its "Import from Devices"
action, which derives the vocabulary from the values already saved on
existing devices. Record why the import is a manual action rather than
an upgrade fixup: it reads device values it does not rewrite, so running
it automatically would resurrect pruned nodes on every chart upgrade.

Also document the new serviceAccountsEnabled option on OIDC clients,
which is opt-in and needs no action on upgrade.
@AlexGodbehere AlexGodbehere merged commit 241d1e3 into main Jul 9, 2026
1 check passed
@AlexGodbehere AlexGodbehere deleted the ago/v6-release-notes branch July 9, 2026 08:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant