Skip to content

feat: add systemInfo volume source with actorIdentity data source - #803

Open
Max Thompson (thompsonmax) wants to merge 5 commits into
agent-substrate:mainfrom
thompsonmax:actor-identity
Open

feat: add systemInfo volume source with actorIdentity data source#803
Max Thompson (thompsonmax) wants to merge 5 commits into
agent-substrate:mainfrom
thompsonmax:actor-identity

Conversation

@thompsonmax

@thompsonmax Max Thompson (thompsonmax) commented Aug 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Part of #802 (first PR: the actorIdentity data source; does not close the issue).

What changed and why

Adds a systemInfo volume source to ActorTemplate — a read-only volume whose files are generated by atelet on every Run/Restore, analogous to Kubernetes projected volumes. The initial data source, actorIdentity, writes the actor's own name to a configurable relative path:

spec:
  volumes:
  - name: system-info
    systemInfo:
      dataSources:
      # Part 1 (this PR): own-metadata projection, downwardAPI-style
      - actorMetadata:
          items:
          - field: name              # enum: name | atespace | uid
            path: actor-name
          - field: atespace
            path: atespace
          - field: uid
            path: actor-uid
  
  containers:
  - name: main
    image: app@sha256:...
    volumeMounts:
    - name: system-info
      mountPath: /run/ate

Because the files are regenerated before the sandbox starts, they carry the resumed actor's own values regardless of what checkpointed state it boots from — the property the old hardcoded /run/ate identity mount provided, now as an explicit, extensible API that future data sources (identity JWTs, certificates — see #802) can slot into.

Behavior change: the automatic /run/ate/actor-id mount is removed; actors must opt in by declaring the volume (the e2e identity probe in this PR is the reference example).

Reviewer notes:

  • Over half the diff is vendored + generated code (cmd/atelet/internal/third_party/atomicwriter/, atelet.pb.go, zz_generated.deepcopy.go, the CRD manifest). The hand-written surface is ~700 lines.
  • System-info volume roots live under a new ActorPath/system-info/ host dir, deliberately separate from durable-dir/: the micro-VM durable machinery snapshots everything under the durable-dir root, and generated identity files must never be captured into snapshots.
  • Supports microVM as well as gVisor.
  • The e2e identity suite exercises the new API end-to-end with unchanged probe binary and assertions. It runs in the kind-cluster CI job (not run locally).

Checklist

  • Issue is linked above
  • Tests pass locally (go test ./...)
  • Root-gated tests pass if applicable (N/A — no root-gated packages touched)
  • Documentation updated if behavior changed (docs/api-guide.md: SystemInfo Volumes section with example)

@thompsonmax Max Thompson (thompsonmax) changed the title Actor identity feat: add systemInfo volume source with actorIdentity data source Aug 7, 2026
juli4n
Julian Gutierrez Oschmann (juli4n) reviewed Aug 9, 2026
View reviewed changes
Comment thread pkg/api/v1alpha1/actortemplate_types.go Outdated
Taahir Ahmed (ahmedtd) and others added 4 commits August 10, 2026 16:23
@ahmedtd @thompsonmax
Remove volume type enum
9686747
@ahmedtd @thompsonmax
System Information Volumes: Part 1 (Actor Identity)
f6fc5a7 
This commit defines a new volume type, SystemInfoVolume, that will serve
a similar purpose as Projected volumes in Kubernetes.  It will support
writing information from multiple sources to automatically-updating
files in the Actor's filesystem.

For a first pass, I have converted the existing hardcoded Actor ID file
to be one of the available information sources in a SystemInfoVolume.

Further work will add Actor Identity JWTs and Actor Identity
certificates.
@thompsonmax
System Information Volumes: Part 1 finishing touches
a33cd2c 
Complete the initial actorIdentity data source support:

- e2e: declare a systemInfo volume in the identity probe's ActorTemplate,
  mounted at /run/ate, replacing the removed automatic identity mount so
  the restore-identity regression gate exercises the new API.
- Validate actorIdentity paths at admission: must be a clean relative
  Unix path (no absolute paths, '..', '.', '//', ':', or control
  characters), and paths must be unique within a volume. Previously bad
  paths were only rejected by the atomic writer at Run/Restore time.
- Unit tests for the ateapi systemInfo conversion and for atelet's
  system-info volume population (extracted into writeSystemInfoVolume).
- Update the stale micro-VM known-gap comment to reference systemInfo
  volumes instead of the removed /run/ate identity mount.
@thompsonmax
Restructure SystemInfo data sources around actorMetadata
6555c5f 
Per the API discussion on agent-substrate#802: substrate has no "actor ID" concept --
resource identity is (atespace, name) plus a server-generated UID. Replace
the actorIdentity data source with an actorMetadata source that projects
each identity field to its own file, downwardAPI-style:

  systemInfo:
    dataSources:
    - actorMetadata:
        items:
        - field: name       # enum: name | atespace | uid
          path: actor-name

- CRD: ActorMetadataDataSource with a field enum and per-item path;
  admission validation for unknown fields, duplicate fields, duplicate
  paths, and non-clean/absolute paths; at most one actorMetadata entry
  per volume keeps paths unique volume-wide.
- atelet proto: ActorMetadataDataSource/ActorMetadataItem with a field
  enum; ateapi converts CRD items to wire items.
- atelet: writeSystemInfoVolume projects name/atespace/uid from the
  Run/Restore request; unknown fields (newer ateapi) are skipped rather
  than written empty.
- e2e: the identity probe projects and serves all three fields; the
  suite now also asserts atespace matches and the projected UID equals
  the control plane's authoritative UID per actor, distinct across
  actors seeded from the same snapshot.
- docs: api-guide section rewritten for actorMetadata.

This also frees the "identity" naming for the planned credential data
sources (actorIdentityToken, actorIdentityCertificate), which relate to
the existing ateapi.ActorIdentity service.
@thompsonmax
microvm: mount system-info volumes over a read-only virtio-fs share
caad956 
SystemInfo volumes were gVisor-only; per the agent-substrate#802 discussion, micro-VM
support lands with Part 1 rather than as a follow-up. The mechanism
mirrors the durable-dir share:

- ateom proto: containers carry system_info_volume_mounts (volume name +
  mount path), populated by atelet's buildAteomWorkloadSpec.
- ateom-microvm serves ateompath.SystemInfoVolumeRootsDir(actorUID) over
  a third virtiofsd (cache=auto: atelet rewrites the contents underneath
  the guest on every restore). The agent mounts the share at sandbox
  creation, and each declaring container gets a READ-ONLY bind from the
  share's per-volume subdirectory to its declared mount path.
- Restore restarts the share's virtiofsd and rewrites its vhost-user
  socket in the snapshot's VM config (matched by fs tag). Nothing is
  restored from the snapshot itself: atelet has already regenerated the
  files with the resumed actor's values, which is the point of
  system-info volumes.
- Checkpoint deliberately ignores the share: the volume roots live
  outside the durable-dir tree precisely so the durable tar can never
  capture generated identity data.
- Replace the stale "KNOWN GAP" comment in spec.go: dropping host-path
  binds in the kata spec shaper is fine because volumes reach micro-VM
  containers via the shares, not spec.Mounts.
@thompsonmax
Max Thompson (thompsonmax) marked this pull request as ready for review August 11, 2026 00:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ahmedtd Taahir Ahmed (ahmedtd) Awaiting requested review from ahmedtd
@juli4n Julian Gutierrez Oschmann (juli4n) Awaiting requested review from juli4n

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@thompsonmax @juli4n @ahmedtd