docs: Add developer-friendly guide to Realm Instances #340

Sukuna0007Abhi · 2025-09-23T17:52:30Z

Description:
This PR adds a comprehensive, practical guide that explains Realm Instances in Arm CCA using real-world analogies and examples. The guide helps developers understand:

What Realm Instances are and why they matter
When to use RIM-only vs RIM+RPV approaches
How to manage Realm Instances in production
Best practices from real-world experience

Key improvements:

Added clear, relatable analogies (workshop tools, assembly line)
Included practical examples that developers can relate to
Used everyday language to explain complex concepts
Added explanatory comments in the technical sections
Made the best practices section more actionable

This documentation addresses the confusion around Realm Instances raised in issue #237, particularly clarifying:

The distinction between single-instance and multi-instance use cases
When and why to use RIM-only vs RIM+RPV approaches
How RIM, RPV, and REM work together in practice

Fixes #237

Ready for Review sir @thomas-fossati @setrofim @yogeshbdeshpande

A comprehensive, practical guide that explains Realm Instances in Arm CCA using real-world analogies and examples. This guide helps developers understand: - What Realm Instances are and why they matter - When to use RIM-only vs RIM+RPV approaches - How to manage Realm Instances in production - Best practices from real-world experience Fixes veraison#237 Signed-off-by: Sukuna0007Abhi <[email protected]>

setrofim · 2025-10-01T09:07:35Z

docs/realm-instance.md

+### The Birth Certificate: Realm Initial Measurements (RIM)
+
+Think of RIM as your Realm's birth certificate - it's the first and most fundamental piece of identity:
+- It's basically a snapshot of your code when it first starts up


It's a hash/digest rather than snapshot.

setrofim · 2025-10-01T09:15:17Z

docs/realm-instance.md

+- Keep track of which instance is which (maintain an RPV registry)
+
+### Watching Your REMs
+This is like having a security camera system:


There more like tripwire alarms than cameras -- they can tell you when something went wrong, but not what (you need event logs for that).

Ok understood

- Change RIM description from 'snapshot' to 'hash/digest' - Update REM analogy from 'security camera system' to 'tripwire alarms' - Clarify that REMs tell you when something went wrong, not what went wrong Signed-off-by: Sukuna0007Abhi <[email protected]>

Sukuna0007Abhi · 2025-10-02T00:33:59Z

Hi sir @setrofim I fixed it as you also approved I am ready for merge also pls review sir @yogeshbdeshpande @thomas-fossati

docs/realm-instance.md

yogeshbdeshpande · 2025-10-03T13:20:53Z

docs/realm-instance.md

+### The Birth Certificate: Realm Initial Measurements (RIM)
+
+Think of RIM as your Realm's birth certificate - it's the first and most fundamental piece of identity:
+- It's basically a hash (digest) of your code when it first starts up


Suggested change

- It's basically a hash (digest) of your code when it first starts up

- It's basically a hash (digest) of the code and optionally configuration of the Realm instance when it first starts up

yogeshbdeshpande · 2025-10-03T13:23:20Z

docs/realm-instance.md

+### The Name Tag: Realm Personalization Value (RPV)
+
+Think of RPV like a name tag for your Realm - it's optional, but super useful when you need it:
+- It's like giving unique names to twins - same base code, different identities


Suggested change

- It's like giving unique names to twins - same base code, different identities

- It's like giving unique names to twins - same base code and configuration, however different identities

yogeshbdeshpande · 2025-10-03T13:23:44Z

docs/realm-instance.md

+Think of RPV like a name tag for your Realm - it's optional, but super useful when you need it:
+- It's like giving unique names to twins - same base code, different identities
+- Without it? Your Realm is one-of-a-kind (like a custom-built tool)
+- With it? You can run multiple copies of the same code (like spinning up multiple web servers)


Suggested change

- With it? You can run multiple copies of the same code (like spinning up multiple web servers)

- With it? You can run multiple copies of the same code and configuration (like spinning up multiple web servers)

yogeshbdeshpande · 2025-10-03T13:25:01Z

docs/realm-instance.md

+- With it? You can run multiple copies of the same code (like spinning up multiple web servers)
+- Perfect for when you need to scale up identical services but keep them separate
+
+### The Health Monitor: Realm Extensible Measurements (REM)


I think, this section needs better exemplification of the real world usage of REM. I will stash another version for this section

Sukuna0007Abhi · 2025-10-03T13:28:02Z

Sure sir @yogeshbdeshpande will update it

yogeshbdeshpande · 2025-10-03T13:28:19Z

docs/realm-instance.md

+- All workers use the same type of tool (same RIM)
+- Each worker's tool has a unique number (RPV)
+- They can all work at the same time without confusion
+- Real example: A web application scaled across multiple servers, all running identical code but handling different users


Line 48: Real example needs improvement, as well with an example:
A Workload needs to do identical job in a batch [parallel processing], so on a Server, Identical N Workloads are instantiated with the same RIM

Ok sir got it

yogeshbdeshpande

See some comments. Good start though, needs some more reviewers and some further work!

Sukuna0007Abhi · 2025-10-03T13:30:37Z

Sure sir thanks for the review 🙏

Signed-off-by: Sukuna0007Abhi <[email protected]> Co-authored-by: Yogesh Deshpande <[email protected]>

- Update RIM description to clarify hash/digest of code and configuration - Improve RPV explanations with better terminology - Add comprehensive real-world examples for REM usage - Enhance assembly line example with parallel processing scenario Signed-off-by: Sukuna0007Abhi <[email protected]>

Sukuna0007Abhi · 2025-10-04T02:18:00Z

Hi sir @yogeshbdeshpande I updated the part you suggested, pls review on your free time sir @yogeshbdeshpande @thomas-fossati

Sukuna0007Abhi · 2025-10-08T01:03:22Z

Pls review sir @SimonFrost-Arm

SimonFrost-Arm

I like the use of analogies here, it's a helpful way to introduce devs to the concepts.
I've left a few comments and I think the REM section needs a bit of a rethink.
It could be useful to have some observations on the verification side of the story - where the source of truth for the reference values come from, while staying in the analogies. For example noting that the birth certificate is trusted because it comes from a govt dept, the RIM reference needs to come from where the Realm initial code had a registration event, such as a software release event.

This doc might be better placed in the docs repo than in services.

Note that this document migh

docs/realm-instance.md

SimonFrost-Arm · 2025-10-08T12:38:52Z

docs/realm-instance.md

+
+## The Basics
+
+Let's break down what a Realm Instance really is in everyday terms. Think of a Realm Instance like a secure container for your application - it's a special, isolated space where your code runs safely in a virtualized environment backed by security guarantees provided by Arm's Confidential Computing Architecture (CCA).


Suggest use a different word than 'container' as that has a specific meaning for how an application gets packaged.
Perhaps 'secured VM' might be a good substitution?

SimonFrost-Arm · 2025-10-08T12:40:41Z

docs/realm-instance.md

+- It's like giving unique names to twins - same base code and configuration, however different identities
+- Without it? Your Realm is one-of-a-kind (like a custom-built tool)
+- With it? You can run multiple copies of the same code and configuration (like spinning up multiple web servers)
+- Perfect for when you need to scale up identical services but keep them separate


maybe worth mentioning that it's often a footprint of instance specific data supplied to the realm

Sure sir @SimonFrost-Arm updated it

Sorry if I wasn't clear - my comment applied to the RPV and not the RIM. Please move (new) line 15 down into the RPV section.

Ok sir @SimonFrost-Arm I updated it, pls review again. In your free time

SimonFrost-Arm · 2025-10-08T12:45:22Z

docs/realm-instance.md

+
+REMs are like ongoing health checks for your Realm:
+- Works like a fitness tracker with 4 different sensors (rem0 through rem3)
+- These are more like tripwire alarms than cameras - they can tell you when something went wrong, but not what (you need event logs for that)


Not sure this analogy works as the REMs are just passive measurements rather than having any active policy.
Perhaps contrast to the measurments made by a car as it progresses on a journey or perhaps path turn choices made when following a map?

Per the real-world comment below, one example is to record execution differences that a workload may have made in response to configuration that it has received (these can affect the workload identity).
Another example might be to identify some state received from the user.

Sukuna0007Abhi · 2025-10-08T13:25:55Z

This doc might be better placed in the docs repo than in services.

Then Sir @SimonFrost-Arm should I close the PR here, then I have to copy the whole content, do the changes and raise a new PR on docs repo..

Or, adding on both services and docs

Or, leave it for now here, //services

What your thoughts about it? Pls reply

SimonFrost-Arm · 2025-10-08T15:50:53Z

This doc might be better placed in the docs repo than in services.

Then Sir @SimonFrost-Arm should I close the PR here, then I have to copy the whole content, do the changes and raise a new PR on docs repo..

Or, adding on both services and docs

Or, leave it for now here, //services

What your thoughts about it? Pls reply

Probably leave it here for the moment.

Sukuna0007Abhi · 2025-10-08T15:53:14Z

This doc might be better placed in the docs repo than in services.

Then Sir @SimonFrost-Arm should I close the PR here, then I have to copy the whole content, do the changes and raise a new PR on docs repo..
Or, adding on both services and docs
Or, leave it for now here, //services
What your thoughts about it? Pls reply

Probably leave it here for the moment.

Ok sir @SimonFrost-Arm then I am doing changes as you said and commiting them & going for review and merge from here, thanks....

- Add CCA-specific intro note at the top - Replace 'container' with 'secured VM' terminology - Add instance-specific data footprint mention in RIM section - Complete REM section overhaul with car journey analogy - Emphasize passive measurements vs active policy enforcement - Add configuration response tracking and user state examples - Add new 'Source of Truth' section with verification context - Use birth certificate/government analogy for trust model All unresolved comments from Simon Frost now addressed. Signed-off-by: Sukuna0007Abhi <[email protected]>

Sukuna0007Abhi · 2025-10-08T16:33:01Z

Ready for review and merge sir @SimonFrost-Arm sir @yogeshbdeshpande

SimonFrost-Arm

Good changes, thanks. See just one more tweak about the data hash.

SimonFrost-Arm · 2025-10-09T08:10:30Z

docs/realm-instance.md

+- It's like giving unique names to twins - same base code and configuration, however different identities
+- Without it? Your Realm is one-of-a-kind (like a custom-built tool)
+- With it? You can run multiple copies of the same code and configuration (like spinning up multiple web servers)
+- Perfect for when you need to scale up identical services but keep them separate


Sorry if I wasn't clear - my comment applied to the RPV and not the RIM. Please move (new) line 15 down into the RPV section.

Sukuna0007Abhi · 2025-10-09T15:01:03Z

Yes sir @SimonFrost-Arm I updated it ready for review and merge ...

Sukuna0007Abhi · 2025-10-09T15:13:24Z

Why the PR is not showing the commit, pls help

- Moved line about footprint of instance-specific data from RIM to RPV section - Addresses reviewer feedback from SimonFrost-Arm about data hash placement Signed-off-by: Sukuna0007Abhi <[email protected]>

The instance-specific data footprint line has been moved from RIM to RPV section as requested by SimonFrost-Arm. Signed-off-by: Sukuna0007Abhi <[email protected]>

Sukuna0007Abhi · 2025-10-09T15:38:53Z

Now ready for review and merge sir @SimonFrost-Arm sir @yogeshbdeshpande

SimonFrost-Arm

LGTM

yogeshbdeshpande

Thank you @Sukuna0007Abhi for putting efforts into creating this Pull Request.

Sukuna0007Abhi force-pushed the docs/realm-instance-clarification branch 2 times, most recently from 424bbd6 to 2325653 Compare September 23, 2025 18:01

Sukuna0007Abhi force-pushed the docs/realm-instance-clarification branch from 2325653 to e361ebf Compare September 23, 2025 18:05

setrofim approved these changes Oct 1, 2025

View reviewed changes

This was referenced Oct 3, 2025

feat: add Valid() methods for TagID and Evidence veraison/swid#45

Merged

Add Evidence validation using swid.Evidence.Valid() method veraison/corim#224

Merged

yogeshbdeshpande reviewed Oct 3, 2025

View reviewed changes

docs/realm-instance.md Outdated Show resolved Hide resolved

yogeshbdeshpande reviewed Oct 3, 2025

View reviewed changes

yogeshbdeshpande requested a review from SimonFrost-Arm October 3, 2025 13:30

Sukuna0007Abhi force-pushed the docs/realm-instance-clarification branch from f79aa4a to 7d0bbc5 Compare October 3, 2025 13:53

Update docs/realm-instance.md

b27b30b

Signed-off-by: Sukuna0007Abhi <[email protected]> Co-authored-by: Yogesh Deshpande <[email protected]>

Sukuna0007Abhi force-pushed the docs/realm-instance-clarification branch from 7d0bbc5 to b27b30b Compare October 3, 2025 13:55

SimonFrost-Arm reviewed Oct 8, 2025

View reviewed changes

SimonFrost-Arm reviewed Oct 9, 2025

View reviewed changes

Sukuna0007Abhi added 2 commits October 9, 2025 15:29

docs: Move instance-specific data footprint line to RPV section

68e7c94

- Moved line about footprint of instance-specific data from RIM to RPV section - Addresses reviewer feedback from SimonFrost-Arm about data hash placement Signed-off-by: Sukuna0007Abhi <[email protected]>

chore: Sync PR with latest changes - Simon's feedback implemented

553228c

The instance-specific data footprint line has been moved from RIM to RPV section as requested by SimonFrost-Arm. Signed-off-by: Sukuna0007Abhi <[email protected]>

Sukuna0007Abhi closed this Oct 9, 2025

Sukuna0007Abhi reopened this Oct 9, 2025

Sukuna0007Abhi force-pushed the docs/realm-instance-clarification branch 3 times, most recently from c2666fe to 68e7c94 Compare October 9, 2025 15:37

Sukuna0007Abhi requested a review from SimonFrost-Arm October 9, 2025 15:37

SimonFrost-Arm approved these changes Oct 10, 2025

View reviewed changes

yogeshbdeshpande approved these changes Oct 10, 2025

View reviewed changes

yogeshbdeshpande merged commit 7079ee4 into veraison:main Oct 10, 2025
9 checks passed

yogeshbdeshpande mentioned this pull request Oct 10, 2025

DOCS: Move Realm Developer friendly guide to docs repo #356

Closed

thisisharsh7 mentioned this pull request Oct 12, 2025

docs: Move Realm Instance guide to CCA musings veraison/docs#70

Merged

	- It's basically a hash (digest) of your code when it first starts up
	- It's basically a hash (digest) of the code and optionally configuration of the Realm instance when it first starts up

	- It's like giving unique names to twins - same base code, different identities
	- It's like giving unique names to twins - same base code and configuration, however different identities

	- With it? You can run multiple copies of the same code (like spinning up multiple web servers)
	- With it? You can run multiple copies of the same code and configuration (like spinning up multiple web servers)


		## The Basics

		Let's break down what a Realm Instance really is in everyday terms. Think of a Realm Instance like a secure container for your application - it's a special, isolated space where your code runs safely in a virtualized environment backed by security guarantees provided by Arm's Confidential Computing Architecture (CCA).

docs: Add developer-friendly guide to Realm Instances #340

docs: Add developer-friendly guide to Realm Instances #340

Conversation

Sukuna0007Abhi commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sukuna0007Abhi commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

yogeshbdeshpande Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yogeshbdeshpande Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sukuna0007Abhi commented Oct 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yogeshbdeshpande left a comment

Choose a reason for hiding this comment

Uh oh!

Sukuna0007Abhi commented Oct 3, 2025

Uh oh!

Sukuna0007Abhi commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Sukuna0007Abhi commented Oct 8, 2025

Uh oh!

SimonFrost-Arm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sukuna0007Abhi Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sukuna0007Abhi commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SimonFrost-Arm commented Oct 8, 2025

Uh oh!

Sukuna0007Abhi commented Oct 8, 2025

Uh oh!

Sukuna0007Abhi commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SimonFrost-Arm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Sukuna0007Abhi commented Sep 23, 2025 •

edited

Loading

Sukuna0007Abhi commented Oct 2, 2025 •

edited

Loading

yogeshbdeshpande Oct 3, 2025 •

edited

Loading

yogeshbdeshpande Oct 3, 2025 •

edited

Loading

Sukuna0007Abhi commented Oct 4, 2025 •

edited

Loading

Sukuna0007Abhi Oct 9, 2025 •

edited

Loading

Sukuna0007Abhi commented Oct 8, 2025 •

edited

Loading

Sukuna0007Abhi commented Oct 8, 2025 •

edited

Loading

Sukuna0007Abhi commented Oct 9, 2025 •

edited

Loading