# IRI Compute Node Resource Definition Profile

**Profile URI:** `https://iri.science/profiles/resource-definition/compute/node`  
**Base Profile:** `https://iri.science/profiles/status/resource`  
**Resource Type:** `urn:doe-iri:resource:compute:node`  
**Status:** Draft  
**Version:** 1.0.0

## 1. Profile Applicability

This profile applies to an IRI Resource representation whose `resource_type` is
`urn:doe-iri:resource:compute:node`. It specializes the [IRI Status Resource
Profile](/profiles/status/resource/); a conforming representation MUST also
satisfy that base profile. The authoritative registration record for this
Resource Type URN is in [Resource Type URNs](https://github.com/doe-iri/iri-facility-api-docs/blob/76a4a0c8992429d0358e8309211cb30a4af1c83c/registry/urns/resource-types.md).

## 2. Introduction

The purpose of this document is to define a common, implementation-independent representation of compute nodes within the DOE Integrated Research Infrastructure (IRI). A compute node represents an individual computing host within a compute system and provides processing, memory, and other local resources used to execute workloads or support operation of the compute environment.

The compute model intentionally separates node identity from CPU and GPU resources. A node may expose relationships to one or more CPU or GPU resources without embedding those processor definitions directly into the node representation.

```text
Compute System
        │
        │ iri:has-node
        ▼
Compute Node
urn:doe-iri:resource:compute:node
        │
        ├── iri:has-cpu ──> CPU
        └── iri:has-gpu ──> GPU
```

The attributes in this profile describe configured characteristics of the node. This version of the profile does not define current load, free memory, allocation condition, health, or workload activity. If represented, the semantics and update behavior of those time-varying values are governed by the applicable IRI API contract and Resource Definition Profile.

## 3. Taxonomy

The following taxonomy identifies the controlled vocabulary values used by this Resource Definition Profile.

```text
urn:doe-iri
│
├── resource
│   └── compute
│       └── node
│
└── compute
    └── node-role
        ├── compute
        ├── login
        └── service
```

## 4. Compute Node Attributes

This Resource Definition Profile defines attributes that MAY be used to describe resources of type `urn:doe-iri:resource:compute:node`.

Except for `schema_version`, attributes are optional. Configured counts and capacities describe the node definition rather than current available capacity.

| Attribute | Version | Type | Description | Mandatory |
|---|---|---|---|---|
| `schema_version` | 1.0.0 | string | Version of the profile definition. | yes |
| `node_roles` | 1.0.0 | Array IRI URN string | Identifies one or more functional roles associated with the node. | no |
| `memory_gib` | 1.0.0 | integer | Configured system memory of the node in GiB (2³⁰ bytes). | no |
| `local_storage_gib` | 1.0.0 | integer | Configured directly attached or node-local storage capacity in GiB (2³⁰ bytes). | no |
| `cpu_socket_count` | 1.0.0 | integer | Configured number of CPU sockets or processor packages associated with the node. | no |
| `cpu_core_count` | 1.0.0 | integer | Configured aggregate CPU core count associated with the node. | no |
| `gpu_count` | 1.0.0 | integer | Configured number of GPU devices associated with the node. | no |
| `vendor` | 1.0.0 | string | Identifies the node vendor when relevant. | no |
| `product` | 1.0.0 | string | Identifies the node product or platform when relevant. | no |
| `model` | 1.0.0 | string | Identifies the node model when relevant. | no |

### 4.1 Compute Node Roles

The `node_roles` attribute identifies functional roles associated with a compute node. A node MAY advertise more than one role. Values are drawn from the `urn:doe-iri:compute:node-role` namespace.

| URN | Short name | Description | Status |
|---|---|---|---|
| `urn:doe-iri:compute:node-role:compute` | Compute | The node is primarily intended to execute computational workloads. | `provisional` |
| `urn:doe-iri:compute:node-role:login` | Login | The node provides interactive access to a compute environment for tasks such as job preparation, submission, and management. | `provisional` |
| `urn:doe-iri:compute:node-role:service` | Service | The node primarily provides supporting services used by the compute environment. | `provisional` |

Example:

```json
{
  "node_roles": [
    "urn:doe-iri:compute:node-role:compute"
  ]
}
```

Node role describes intended function and SHOULD NOT be interpreted as current availability or authorization.

### 4.2 Configured Node Capacity

`memory_gib`, `local_storage_gib`, `cpu_socket_count`, `cpu_core_count`, and `gpu_count` describe configured node capacity.

For example:

```json
{
  "memory_gib": 512,
  "local_storage_gib": 2048,
  "cpu_socket_count": 2,
  "cpu_core_count": 128,
  "gpu_count": 4
}
```

These values SHOULD NOT be interpreted as current available memory, free local storage, idle CPU cores, or available GPUs. If such time-varying values are represented, their semantics and update behavior are governed by the applicable IRI API contract and Resource Definition Profile.

Where CPU and GPU resources are separately exposed through `iri:has-cpu` and `iri:has-gpu`, the aggregate counts MAY be derivable from those relationships. Facilities MAY still publish counts when detailed processor topology is not exposed.

### 4.3 Vendor, Product, and Model

The optional `vendor`, `product`, and `model` attributes provide descriptive implementation information for the node and are represented as strings.

## 5 Compute Node JSON Schema

```yaml
components:
  schemas:

    IriUrn:
      type: string
      pattern: '^urn:doe-iri:[A-Za-z0-9][A-Za-z0-9:._~-]*$'

    ComputeNodeAttributes:
      type: object
      description: >
        Attributes describing a compute node resource with resource type
        urn:doe-iri:resource:compute:node.
      required:
        - schema_version

      properties:

        schema_version:
          type: string
          enum:
            - "1.0.0"
          example: "1.0.0"

        node_roles:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/IriUrn'

        memory_gib:
          type: integer
          format: int64
          minimum: 0

        local_storage_gib:
          type: integer
          format: int64
          minimum: 0

        cpu_socket_count:
          type: integer
          minimum: 0

        cpu_core_count:
          type: integer
          minimum: 0

        gpu_count:
          type: integer
          minimum: 0

        vendor:
          type: string

        product:
          type: string

        model:
          type: string
```

## 6 Example Compute Node JSON Instance

```json
{
  "schema_version": "1.0.0",
  "node_roles": [
    "urn:doe-iri:compute:node-role:compute"
  ],
  "memory_gib": 512,
  "local_storage_gib": 2048,
  "cpu_socket_count": 2,
  "cpu_core_count": 128,
  "gpu_count": 4,
  "vendor": "Example Vendor",
  "product": "Example Node Platform",
  "model": "X1000"
}
```

## 7. Applicable Operation Affordances

This profile supplements the [common Resource profile](/profiles/status/resource/).
The registered relation definitions remain authoritative for operation
semantics, and the applicable deployed OpenAPI description remains
authoritative for the invocation contract.

The filesystem operation family is conditionally applicable only when this
specific compute node is explicitly configured as a filesystem execution
context and the adapter establishes an unambiguous path namespace and
operation context:

- metadata and security: [`iri:change-file-mode`](/rels/change-file-mode/),
  [`iri:change-file-owner`](/rels/change-file-owner/),
  [`iri:identify-file`](/rels/identify-file/),
  [`iri:stat-file`](/rels/stat-file/), and
  [`iri:checksum-file`](/rels/checksum-file/);
- directory and read: [`iri:create-directory`](/rels/create-directory/),
  [`iri:create-symlink`](/rels/create-symlink/),
  [`iri:list-directory`](/rels/list-directory/),
  [`iri:read-file-head`](/rels/read-file-head/), and
  [`iri:read-file-tail`](/rels/read-file-tail/);
- content transfer: [`iri:view-file`](/rels/view-file/),
  [`iri:copy-path`](/rels/copy-path/),
  [`iri:download-file`](/rels/download-file/), and
  [`iri:upload-file`](/rels/upload-file/); and
- mutation and archive: [`iri:remove-path`](/rels/remove-path/),
  [`iri:compress-paths`](/rels/compress-paths/),
  [`iri:extract-archive`](/rels/extract-archive/), and
  [`iri:move-path`](/rels/move-path/).

[`iri:resolve-storage-locations`](/rels/resolve-storage-locations/)
MAY be advertised only when storage-location resolution is explicitly
configured for this node. Compute-job relations and
`iri:get-storage-access-endpoints` do not apply to a compute-node Resource.
Membership in a compute system, node roles, and configured capacity do not
confer those operations or a filesystem execution context.

When any applicable operation relation is advertised, the representation MUST
also advertise at least one applicable `service-desc` whose deployed OpenAPI
contains the matching canonical `x-iri-relation` binding. An operation link
targets an operation entry point and MUST NOT carry an IRI representation
`profile`. Clients MUST NOT infer an operation path from the Resource Type,
profile URI, Resource identifier, topology, or node attributes.

A provider MAY omit an operation link because it is not configured,
applicable, or visible to the requester. Absence means only that the operation
is not advertised in the current representation. Presence grants no
permission and guarantees no successful invocation.

---

*DOE Integrated Research Infrastructure — URN Registry: Compute Node*