How to Deliver Actor Identity Information Using SystemInfo Volumes in Agent Substrate

Agent Substrate's SystemInfo volumes automatically project an actor's identity fields—metadata.name, metadata.atespace, and metadata.uid—into immutable files mounted inside the actor's filesystem, enabling secure self-identification without sidecars or environment variables.

The Agent Substrate control plane provides a declarative mechanism to deliver actor identity information using SystemInfo volumes. This volume type, analogous to Kubernetes' downward API but with stronger immutability guarantees, writes identity metadata directly into the actor's filesystem at startup. Configuration occurs entirely within the ActorTemplate spec, making the approach fully declarative and version-controlled.

Understanding SystemInfo Volume Architecture

SystemInfoVolumeSource Definition

In pkg/api/v1alpha1/actortemplate_types.go (lines 65-82), the SystemInfoVolumeSource struct declares a volume that exposes system-level information to the actor. This source acts as the container for data projection mechanisms that map internal actor metadata to filesystem paths.

ActorMetadataDataSource and ActorMetadataItem

The ActorMetadataDataSource (lines 95-110) is the sole data source capable of projecting identity fields. It contains a list of ActorMetadataItem objects (lines 59-93), where each item specifies:

• Field: The identity attribute to expose (name, atespace, or uid)
• Path: The relative Unix file path inside the volume where the value is written

The substrate controller resolves this data source during actor initialization, gathering values from the actor's ObjectMeta and projecting them into the mounted volume.

Configuring SystemInfo Volumes for Identity Projection

To deliver actor identity information using SystemInfo volumes, you define the projection rules within the volumes array of your ActorTemplate. Each SystemInfoVolumeSource may contain exactly one actorMetadata entry under dataSources, which lists the specific identity fields to expose.

Valid identity fields include:

• name: The actor's metadata.name
• atespace: The atespace the actor belongs to
• uid: The unique UID of the actor object

Validation rules enforced by the API server:

• Only one actorMetadata entry permitted per SystemInfo volume
• Paths must be clean relative Unix paths (no leading /, no .. components)
• No duplicate fields or duplicate paths allowed (enforced by XValidation on the Items array)

Practical Implementation Example

The following ActorTemplate configuration mounts a SystemInfo volume at /etc/sysinfo and projects three identity files:

apiVersion: substrate.dev/v1alpha1
kind: ActorTemplate
metadata:
  name: example
spec:
  volumes:
  - name: sysinfo
    systemInfo:
      dataSources:
      - actorMetadata:
          items:
          - field: name
            path: identity/name
          - field: atespace
            path: identity/atespace
          - field: uid
            path: identity/uid

  containers:
  - name: app
    image: ghcr.io/example/app@sha256:deadbeef...
    volumeMounts:
    - name: sysinfo
      mountPath: /etc/sysinfo

When this template is applied, the substrate controller creates three files under /etc/sysinfo/identity/:

• name contains the actor's metadata.name
• atespace contains the actor's atespace
• uid contains the actor's unique UID

The container can read these files (e.g., cat /etc/sysinfo/identity/name) to obtain its identity. The CSI driver implementation in internal/volume/csi/plugin.go handles the actual mount operations, ensuring the files appear before the actor process starts.

Lifecycle Guarantees and Security Properties

SystemInfo volumes provide stronger guarantees than traditional environment variables or init containers. The control plane writes identity values once during actor creation, and these values remain immutable throughout the actor's lifecycle—including across suspend, resume, and migration operations.

Key security characteristics:

• Files are created without trailing newlines to prevent parsing ambiguity
• Content is read-only from the actor's perspective
• Values are sourced directly from the authoritative ObjectMeta and never mutated by the actor

This immutability makes SystemInfo volumes suitable for:

• Embedding identity tokens in downstream service authentication headers
• Static configuration files requiring stable actor identifiers
• Debugging and audit logging inside the actor process

Summary

• SystemInfo volumes in Agent Substrate project actor identity fields from ObjectMeta into the filesystem via ActorMetadataDataSource and ActorMetadataItem configurations defined in pkg/api/v1alpha1/actortemplate_types.go.
• Identity projection supports three fields—name, atespace, and uid—written to configurable relative paths within the volume mount.
• Validation rules restrict each volume to one actorMetadata entry with unique, clean relative paths to prevent misconfiguration.
• Immutability guarantees ensure files remain constant across the entire actor lifecycle, making them reliable for security-sensitive operations.
• CSI integration via internal/volume/csi/plugin.go ensures volumes mount before actor startup with read-only, newline-stripped content.

Frequently Asked Questions

What identity fields can be projected using SystemInfo volumes?

Agent Substrate supports projecting three specific identity fields: name (the actor's metadata.name), atespace (the atespace the actor belongs to), and uid (the actor's unique identifier). These are defined in the ActorMetadataItem struct within pkg/api/v1alpha1/actortemplate_types.go (lines 59-93). Each field maps to a separate file inside the mounted volume at the relative path you specify.

How does Agent Substrate ensure the immutability of identity files?

The substrate control plane writes identity values exactly once during actor initialization, sourcing data directly from the actor's ObjectMeta. Because the CSI driver implementation in internal/volume/csi/plugin.go mounts these files as read-only and the control plane never updates them, the values persist unchanged through suspend, resume, and migration operations. This design prevents both accidental modification and tampering by the actor process.

Can I modify the identity files after the actor starts?

No. SystemInfo volumes are read-only from the actor's perspective. The files are created by the control plane before the actor container starts, and the volume mount permissions prevent write access. This restriction ensures that identity information remains trustworthy for authentication and logging purposes throughout the actor's lifecycle.

What validation prevents misconfiguration of SystemInfo volumes?

The API server enforces several validation rules on SystemInfoVolumeSource objects: only one actorMetadata entry is permitted per volume, file paths must be clean relative Unix paths (no leading or trailing slashes, no .. components), and duplicate fields or paths within the items array are prohibited via XValidation markers. These constraints are defined in pkg/api/v1alpha1/actortemplate_types.go and prevent runtime mounting errors or ambiguous file layouts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}