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

> Learn how to deliver actor identity information using SystemInfo volumes in Agent Substrate. Securely project identity fields into actor filesystems without sidecars or environment variables.

- Repository: [Agent Substrate/substrate](https://github.com/agent-substrate/substrate)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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`](https://github.com/agent-substrate/substrate/blob/main/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:

```yaml
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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/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`](https://github.com/agent-substrate/substrate/blob/main/pkg/api/v1alpha1/actortemplate_types.go) and prevent runtime mounting errors or ambiguous file layouts.