feat: Introduce separate replica version by frankdavid · Pull Request #11401 · dfinity/ic

frankdavid · 2026-09-01T15:15:25Z

There used to be a single version: the one under /opt/ic/share/version.txt, read by the orchestrator and passed to the replica. During fast GuestOS upgrade, the replica binaries are hot-swapped via an overlay while the node keeps running the old GuestOS. The base GuestOS version and the replica version must be distinguished.

PlatformVersion (new struct in ic-types, next to ReplicaVersion) holds both guestos_version (the GuestOS the node booted from) and replica_version (the running replica binary). replica_version: ReplicaVersion in ReplicaConfig is replaced by platform_version: PlatformVersion.
Build: the GuestOS image now ships a second version artifact, /opt/ic/share/binary_version.txt (plus its -test variant). During a fast upgrade, the sysext overlay will shadow it with the post-upgrade version, while version.txt — now explicitly the GuestOS version — is never shadowed.
Orchestrator: reads both files (--version-file → binary version, --guestos-version-file → GuestOS version) and passes them when starting the replica process.
Observability: /api/v2/status gains an optional guestos_version field alongside impl_version.
Metrics: custom-metrics.sh now also exports a binary_version metric.

There used to be a single version: the one under `/opt/ic/share/version.txt`, read by the orchestrator and passed to the replica. During fast GuestOS upgrade, the replica binaries are hot-swapped via an overlay while the node keeps running the old GuestOS. The base GuestOS version and the replica version must be distinguished. - **`PlatformVersion`** (new struct in `ic-types`, next to `ReplicaVersion`) holds both `guestos_version` (the GuestOS the node booted from) and `replica_version` (the running replica binary). `replica_version: ReplicaVersion` in ``ReplicaConfig` is replaced by `platform_version: PlatformVersion`. - **Build**: the GuestOS image now ships a second version artifact, `/opt/ic/share/binary_version.txt` (plus its `-test` variant). During a fast upgrade, the sysext overlay will shadow it with the post-upgrade version, while `version.txt` — now explicitly the GuestOS version — is never shadowed. - **Orchestrator**: reads both files (`--version-file` → binary version, `--guestos-version-file` → GuestOS version) and passes them when starting the replica process. - **Observability**: `/api/v2/status` gains an optional `guestos_version` field alongside `impl_version`. - **Metrics**: `custom-metrics.sh` now also exports a binary_version metric.

zeropath-ai · 2026-09-01T15:16:07Z

✅ No security or compliance issues detected. Reviewed everything up to d9e0da2.

Security Overview

🔎 Scanned files: 51 changed file(s)
🔗 Scan Link: https://zeropath.com/app/repositories/f5e9d2bb-29a4-4b64-902a-391d65fd8b2d?scanId=960b44c9-df58-41d5-bb78-62fa87c1a252&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► ic-os/components/guestos/ic-replica.service Update ExecStart and add replica/version-file references ► ic-os/components/monitoring/guestos/custom-metrics.sh Add binary_version metric and integrate into main metric updates ► ic-os/components/monitoring/metrics-proxy/guestos/metrics-proxy.yaml Keep binary_version metric in proxies ► ic-os/defs.bzl Copy binary_version.txt and optional test file during upgrades ► rs/boundary_node/ic_boundary/src/http/handlers.rs Add guestos_version field to status response ► rs/consensus/dkg/src/dkg_key_manager.rs Switch test imports to test_platform_version and platform_version usage in tests ► rs/consensus/dkg/src/lib.rs Preserve platform_version in ReplicaConfig while initializing ReplicaVersion ► rs/consensus/dkg/src/payload_validator.rs Use platform_version where replica_version previously referenced ► rs/consensus/mocks/src/lib.rs Update mocks to use PlatformVersion and adjust replica_version handling ► rs/consensus/src/consensus/batch_delivery.rs Use platform_version in replica_config when constructing test configs ► rs/consensus/src/consensus/block_maker.rs Pass replica_version() from replica_config in block maker calls ► rs/consensus/src/consensus/catchup_package_maker.rs Use replica_version() from replica_config in package creation ► rs/consensus/src/consensus/finalizer.rs Use replica_version() instead of replica_version.clone() in finalization ► rs/consensus/src/consensus/malicious_consensus.rs Use replica_version() rather than replica_version.clone() ► rs/consensus/src/consensus/notary.rs Use replica_version() in multiple call sites ► rs/consensus/src/consensus/random_beacon_maker.rs Use replica_version() instead of replica_version.clone() ► rs/consensus/src/consensus/random_tape_maker.rs Use replica_version() instead of replica_version.clone() ► rs/consensus/src/consensus/share_aggregator.rs Use platform_version in replica_config construction ► rs/consensus/src/consensus/validator.rs Use replica_version() instead of replica_version for comparisons ► rs/consensus/tests/framework/types.rs Pass replica_version() to ConsensusDependencies ► rs/consensus/tests/framework/test_runner.rs Use test_platform_version in replica configs ► rs/consensus/tests/payload.rs Update ReplicaConfig to include PlatformVersion and adapt replica_version usage ► rs/determinism_test/src/setup.rs Use platform_version in ReplicaConfig ► rs/http_endpoints/public/src/dashboard.rs Dashboard display uses platform_version instead of replica_version ► rs/http_endpoints/public/src/lib.rs Dashboard and server setup updated to platform_version ► rs/http_endpoints/public/src/status.rs Status service now uses platform_version and guestos_version fields ► rs/http_endpoints/public/templates/dashboard.html Dashboard displays replica_version via platform_version and adds GuestOS Version display ► rs/http_endpoints/public/tests/common/mod.rs Update test imports to use test_platform_version and adapt types ► rs/http_endpoints/public/src/status.rs Adjust status response construction to include platform_version and guestos_version ► rs/http_endpoints/public/tests/common/mod.rs Update imports to test_platform_version ► rs/consensus/tests/payload.rs Adjust imports to include PlatformVersion and update ReplicaConfig construction ► rs/consensus/tests/framework/test_runner.rs Update test replica configs to use test_platform_version ► rs/http_endpoints/public/src/dashboard.rs Adjust type imports to PlatformVersion and related fields ► rs/consensus/tests/payload.rs Adjust replica_config.replica_version usage to replica_version() where applicable ► rs/http_endpoints/public/src/status.rs Update status fields to reference platform_version and guestos_version

zeropath-ai · 2026-09-01T15:16:29Z

✅ No security or compliance issues detected. Reviewed everything up to d9e0da2.

Security Overview

🔎 Scanned files: 51 changed file(s)
🔗 Scan Link: https://zeropath.com/app/repositories/6992424c-495e-4621-b441-efd6821a4be6?scanId=2e54dd86-d7f2-4ac7-9d31-e43a5031e69f&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► ic-os/components/guestos/ic-replica.service Update ExecStart and add replica/version-file references ► ic-os/components/monitoring/guestos/custom-metrics.sh Add binary_version metric and integrate into main metric updates ► ic-os/components/monitoring/metrics-proxy/guestos/metrics-proxy.yaml Keep binary_version metric in proxies ► ic-os/defs.bzl Copy binary_version.txt and optional test file during upgrades ► rs/boundary_node/ic_boundary/src/http/handlers.rs Add guestos_version field to status response ► rs/consensus/dkg/src/dkg_key_manager.rs Switch test imports to test_platform_version and platform_version usage in tests ► rs/consensus/dkg/src/lib.rs Preserve platform_version in ReplicaConfig while initializing ReplicaVersion ► rs/consensus/dkg/src/payload_validator.rs Use platform_version where replica_version previously referenced ► rs/consensus/mocks/src/lib.rs Update mocks to use PlatformVersion and adjust replica_version handling ► rs/consensus/src/consensus/batch_delivery.rs Use platform_version in replica_config when constructing test configs ► rs/consensus/src/consensus/block_maker.rs Pass replica_version() from replica_config in block maker calls ► rs/consensus/src/consensus/catchup_package_maker.rs Use replica_version() from replica_config in package creation ► rs/consensus/src/consensus/finalizer.rs Use replica_version() instead of replica_version.clone() in finalization ► rs/consensus/src/consensus/malicious_consensus.rs Use replica_version() rather than replica_version.clone() ► rs/consensus/src/consensus/notary.rs Use replica_version() in multiple call sites ► rs/consensus/src/consensus/random_beacon_maker.rs Use replica_version() instead of replica_version.clone() ► rs/consensus/src/consensus/random_tape_maker.rs Use replica_version() instead of replica_version.clone() ► rs/consensus/src/consensus/share_aggregator.rs Use platform_version in replica_config construction ► rs/consensus/src/consensus/validator.rs Use replica_version() instead of replica_version for comparisons ► rs/consensus/tests/framework/types.rs Pass replica_version() to ConsensusDependencies ► rs/consensus/tests/framework/test_runner.rs Use test_platform_version in replica configs ► rs/consensus/tests/payload.rs Update ReplicaConfig to include PlatformVersion and adapt replica_version usage ► rs/determinism_test/src/setup.rs Use platform_version in ReplicaConfig ► rs/http_endpoints/public/src/dashboard.rs Dashboard display uses platform_version instead of replica_version ► rs/http_endpoints/public/src/lib.rs Dashboard and server setup updated to platform_version ► rs/http_endpoints/public/src/status.rs Status service now uses platform_version and guestos_version fields ► rs/http_endpoints/public/templates/dashboard.html Dashboard displays replica_version via platform_version and adds GuestOS Version display ► rs/http_endpoints/public/tests/common/mod.rs Update test imports to use test_platform_version and adapt types ► rs/http_endpoints/public/src/status.rs Adjust status response construction to include platform_version and guestos_version ► rs/http_endpoints/public/tests/common/mod.rs Update imports to test_platform_version ► rs/consensus/tests/payload.rs Adjust imports to include PlatformVersion and update ReplicaConfig construction ► rs/consensus/tests/framework/test_runner.rs Update test replica configs to use test_platform_version ► rs/http_endpoints/public/src/dashboard.rs Adjust type imports to PlatformVersion and related fields ► rs/consensus/tests/payload.rs Adjust replica_config.replica_version usage to replica_version() where applicable ► rs/http_endpoints/public/src/status.rs Update status fields to reference platform_version and guestos_version

Copilot

Pull request overview

Introduces separate GuestOS and replica binary version tracking for fast upgrades.

Changes:

Adds PlatformVersion and propagates it through replica and consensus.
Exposes GuestOS version through status APIs and metrics.
Packages separate GuestOS and binary version artifacts.

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`rs/types/types/src/replica_version.rs`	Defines `PlatformVersion`.
`rs/types/types/src/replica_config.rs`	Uses platform version configuration.
`rs/types/types/src/messages/http/tests.rs`	Updates status fixtures.
`rs/types/types/src/messages/http.rs`	Adds GuestOS status field.
`rs/types/types/src/lib.rs`	Exports `PlatformVersion`.
`rs/types/types_test_utils/src/ids.rs`	Adds platform-version fixture.
`rs/replica/src/setup_ic_stack.rs`	Propagates platform versions.
`rs/replica/src/args.rs`	Adds GuestOS version argument.
`rs/replica/setup_ic_network/src/lib.rs`	Passes platform versions into consensus.
`rs/replica/bin/replica/main.rs`	Constructs runtime platform version.
`rs/replica_tests/src/lib.rs`	Updates replica test setup.
`rs/replay/src/validator.rs`	Updates replay configuration.
`rs/orchestrator/src/upgrade.rs`	Tracks both versions during upgrades.
`rs/orchestrator/src/processes.rs`	Passes both versions to replicas.
`rs/orchestrator/src/orchestrator.rs`	Loads both version files.
`rs/orchestrator/src/args.rs`	Adds GuestOS version-file argument.
`rs/https_outcalls/consensus/src/pool_manager.rs`	Uses binary version for artifacts.
`rs/http_endpoints/public/tests/common/mod.rs`	Updates endpoint test setup.
`rs/http_endpoints/public/src/status.rs`	Reports both versions.
`rs/http_endpoints/public/src/lib.rs`	Propagates platform versions.
`rs/determinism_test/src/setup.rs`	Updates determinism fixture.
`rs/consensus/tests/payload.rs`	Updates payload test configuration.
`rs/consensus/tests/framework/types.rs`	Uses nested replica version.
`rs/consensus/tests/framework/test_runner.rs`	Updates consensus fixtures.
`rs/consensus/src/consensus/validator.rs`	Validates binary versions.
`rs/consensus/src/consensus/share_aggregator.rs`	Updates test configuration.
`rs/consensus/src/consensus/random_tape_maker.rs`	Emits binary version.
`rs/consensus/src/consensus/random_beacon_maker.rs`	Emits binary version.
`rs/consensus/src/consensus/notary.rs`	Uses binary version.
`rs/consensus/src/consensus/malicious_consensus.rs`	Uses binary version.
`rs/consensus/src/consensus/finalizer.rs`	Uses binary version.
`rs/consensus/src/consensus/catchup_package_maker.rs`	Uses binary version.
`rs/consensus/src/consensus/block_maker.rs`	Uses binary version.
`rs/consensus/src/consensus/batch_delivery.rs`	Updates test configuration.
`rs/consensus/mocks/src/lib.rs`	Builds platform-version mocks.
`rs/consensus/dkg/src/payload_validator.rs`	Updates test configuration.
`rs/consensus/dkg/src/lib.rs`	Extracts binary version for DKG.
`rs/consensus/dkg/src/dkg_key_manager.rs`	Updates test configuration.
`rs/boundary_node/ic_boundary/src/http/handlers.rs`	Updates status response construction.
`ic-os/defs.bzl`	Packages binary version artifacts.
`ic-os/components/monitoring/guestos/custom-metrics.sh`	Adds binary-version metric.
`ic-os/components/guestos/ic-replica.service`	Supplies both version files.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

Pull request overview

Copilot reviewed 44 out of 44 changed files in this pull request and generated 2 comments.

Co-authored-by: Pierugo Pace <pierugo.pace@dfinity.org>

pierugo-dfinity · 2026-09-03T08:36:52Z

            registry_replicator.get_latest_certified_time(),
            processes_manager,
            Arc::clone(&subnet_assignment),
            replica_version,


I think it would be a good idea to report the GuestOS version in the orchestrator's dashboard as well.

Reopening because I don't think this was addressed

Co-authored-by: Pierugo Pace <pierugo.pace@dfinity.org>

pierugo-dfinity · 2026-09-03T14:44:06Z

+    update_binary_version_metric
    update_guestos_boot_action_metric
    update_config_version_metric
    update_tee_metrics


Should we stay consistent and replace all binary_version with replica_version? This also applies to metrics-proxy.yaml and ic-os/defs.bzl

pierugo-dfinity · 2026-09-04T10:05:38Z

@@ -68,7 +68,7 @@ impl OrchestratorMetrics {
            orchestrator_info: metrics_registry.int_gauge_vec(
                "ic_orchestrator_info",
                "version info for the internet computer orchestrator running.",


Suggested change

"version info for the internet computer orchestrator running.",

"Replica & GuestOS versions info for the running Internet Computer orchestrator",

pierugo-dfinity · 2026-09-04T13:28:30Z

    pub skip_prompts: bool,

+    #[clap(long)]
+    /// The GuestOS version to report; defaults to the replica version.


Suggested change

/// The GuestOS version to report; defaults to the replica version.

/// The GuestOS version the validator uses; defaults to the replica version.

pierugo-dfinity · 2026-09-04T14:31:19Z

+    pub guestos_version: ReplicaVersion,
+    /// The replica binary version, possibly hot-swapped by a fast upgrade.
+    pub replica_version: ReplicaVersion,
+}


I'm starting to lean towards introducing type GuestosVersion = VersionOf<GuestosVersionTag> and type ReplicaVersion = VersionOf<ReplicaVersionTag>, i.e. have them share same semantics (same methods, same representation in memory) while keeping the two types strictly different from one another.
I think this should be more robust on the long-run.

But this would probably deserve its own PR.

frankdavid added 2 commits September 1, 2026 15:14

GuestOS version

0627e71

frankdavid requested review from a team as code owners September 1, 2026 15:15

github-actions Bot added the feat label Sep 1, 2026

Automatically fixing code for linting and formatting issues

cc6c2c2

github-actions Bot added @node @core-protocol labels Sep 1, 2026

frankdavid requested a balanced review from Copilot September 1, 2026 15:23

Copilot started reviewing on behalf of frankdavid September 1, 2026 15:23 View session

Copilot AI reviewed Sep 1, 2026

View reviewed changes

Comment thread ic-os/components/monitoring/guestos/custom-metrics.sh

Comment thread rs/http_endpoints/public/src/status.rs

Address copilot comments

d0fd2eb

frankdavid requested a review from a team as a code owner September 1, 2026 16:00

frankdavid requested a balanced review from Copilot September 1, 2026 16:00

github-actions Bot added the @dre label Sep 1, 2026

Copilot started reviewing on behalf of frankdavid September 1, 2026 16:00 View session

Copilot AI reviewed Sep 1, 2026

View reviewed changes

Comment thread rs/orchestrator/src/processes.rs

Comment thread rs/consensus/tests/framework/test_runner.rs Outdated

fmt

57c0c96

pierugo-dfinity reviewed Sep 2, 2026

View reviewed changes

Update rs/orchestrator/src/orchestrator.rs

2a70de9

Co-authored-by: Pierugo Pace <pierugo.pace@dfinity.org>

Bownairo approved these changes Sep 2, 2026

View reviewed changes

frankdavid added 2 commits September 2, 2026 18:19

Address comments

e7f7086

Add guestos_version to UpgradeTestScenario

18d68d8

pierugo-dfinity reviewed Sep 3, 2026

View reviewed changes

frankdavid and others added 4 commits September 3, 2026 13:38

Update rs/replica/bin/replica/main.rs

c3e13d4

Co-authored-by: Pierugo Pace <pierugo.pace@dfinity.org>

Add platform_version to dashboard

3a96aac

replica_config.replica_version()

00d19ac

Use different test_replica_version and test_guestos_version

f8415eb

frankdavid added 5 commits September 3, 2026 14:09

Don't clone replica_version

89d8324

Don't clone replica_version 2

e5c7346

Remove clones

0baa1bc

Add ic_guestos_version to orchestrator_info

4c2fcc8

Make clippy happy with too_many_arguments in tests

8c0476c

pierugo-dfinity reviewed Sep 3, 2026

View reviewed changes

Comment thread rs/http_endpoints/public/src/lib.rs Outdated

Comment thread rs/replay/src/validator.rs Outdated

Comment thread rs/orchestrator/src/orchestrator.rs Outdated

pierugo-dfinity reviewed Sep 3, 2026

View reviewed changes

frankdavid added 2 commits September 3, 2026 16:54

Pass guestos version to replay

5aa994b

Pass guestos version to BoundaryNodeManager

d9e0da2

pierugo-dfinity reviewed Sep 4, 2026

View reviewed changes

	"version info for the internet computer orchestrator running.",
	"Replica & GuestOS versions info for the running Internet Computer orchestrator",

	/// The GuestOS version to report; defaults to the replica version.
	/// The GuestOS version the validator uses; defaults to the replica version.

Uh oh!

Conversation

frankdavid commented Sep 1, 2026 • edited by Bownairo Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zeropath-ai Bot commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zeropath-ai Bot commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pierugo-dfinity Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

pierugo-dfinity Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pierugo-dfinity Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

pierugo-dfinity Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

pierugo-dfinity Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

pierugo-dfinity Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

frankdavid commented Sep 1, 2026 •

edited by Bownairo

Loading

zeropath-ai Bot commented Sep 1, 2026 •

edited

Loading

zeropath-ai Bot commented Sep 1, 2026 •

edited

Loading