Skip to main content

Payload metadata

Payload metadata consists of key-value pairs, which can be attached to individual payloads, and can be changed over the payload's lifetime.

Common use-cases for payload metadata include:

  • Passing data to or from individual payloads (e.g. passing match details from a match maker to the payload upon reservation, or for a payload to signal its match state back to a matchmaker),
  • Debugging a payload's internal state by exposing metadata from the payload,
  • Reservations, by having more fine-grained control over which payloads to prioritise for reservation.

There are two types of metadata:

  • labels
    • can be used to identify payloads, for e.g. filtering eligible payloads in a reservation request,
    • values have to be in a specific format and length.
  • annotations
    • cannot be used to identify payloads,
    • but can contain arbitrary values (up to 256kB in size).

Reading / writing metadata​

Metadata can be read and written using the Orchestration API.

Payloads themselves can write and read their own metadata using the Payload Local API.

Set metadata on reservation​

When reserving a payload, it's possible to specify metadata which gets added to the reserved payload.

Can be used to e.g. pass custom match settings to the payload.

Using metadata to reserve specific payloads​

See this guide for how to use metadata to reserve specific payloads.

Valid metadata​

There are some restrictions on what a valid metadata key/value is:

Metadata keys (labels and annotations)

  • must be 59 characters or less (cannot be empty),
  • must begin and end with an alphanumeric character ([a-z0-9A-Z]),
  • can contain dashes (-), underscores (_), dots (.), and alphanumeric characters in between.

Examples:

  • ✅ foo
  • ✅ foo_123
  • ❌ (empty)
  • ❌ _foo
  • ❌ foo/bar

Label values

  • must be 63 characters or less (can be empty),
  • unless empty, must begin and end with an alphanumeric character,
  • can contain dashes (-), underscores (_), dots (.), and alphanumeric characters in between.

Examples:

  • ✅ bar
  • ✅ bar.456
  • ✅ (empty)
  • ❌ bar.
  • ❌ bar/baz
  • ❌ bar and baz
  • ❌ {"foo": "bar"}
  • ❌ 64 characters or more

Annotation values

  • can have arbitrary data,
  • total size of all annotations can be at most 256kB.

Examples:

  • ✅ bar
  • ✅ bar/baz
  • ✅ {"foo": "bar"}
  • ✅ Human-readable text
  • ✅ SGVsbG8gdGhlcmUu
  • ✅ (empty)
  • ❌ total size of all annotations larger than 256kB

Persisting Artefacts​

Payloads are ephemeral, but it's possible to persist and retrieve data from them in the form of files. See How to create and access artefacts.