HostPodSet - IDYL Docs

A HostPodSet keeps a counted set of host Pods. A host Pod runs no workload of its own: it reserves a CPU and memory envelope on a node for isolated units that a node agent creates inside it later, through the node’s own contract. The HostPodSet decides how many hosts exist, where they may be placed, and the isolation class of the units they hold; it says nothing about what those units run or for whom beyond its opaque owner. A HostPodSet is reconciled like a ReplicaSet: the platform creates and removes host Pods until the placed set matches the desired count, and when the template changes it replaces hosts according to the strategy, draining each host before it is removed.

Minimal manifest

kind: HostPodSet
metadata:
  name: sandbox-hosts
  subnet: "100000000001"
spec:
  owner: example.com/sandboxes
  hosts:
    max: 4
  strategy:
    type: RollingUpdate
  template:
    isolation: secure-container
    capacity:
      cpu: "2"
      memory: 4Gi

Example manifest

kind: HostPodSet
metadata:
  name: sandbox-hosts
  subnet: "100000000001"
  labels:
    app: sandbox-hosts
spec:
  owner: example.com/sandboxes
  hosts:
    count: 2
    min: 1
    max: 8
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1
  template:
    isolation: microvm
    capacity:
      cpu: "4"
      memory: 8Gi
    placement:
      fleet: "391742608215"

Field reference

kindstringRequired

Resource kind. The value is case-sensitive.

Value HostPodSet

metadataobjectRequired

Top-level workload metadata.

metadata.namespaceobjectOptional

Namespace scope embedded in the manifest. Scoped SDK clients populate it when omitted and refuse a manifest that states a different scope.

Format Explicit scope or SDK client scope

metadata.namespace.accountIdstringOptional

Account that owns the Namespace.

Format 12-digit account ID

metadata.namespace.namespacestringOptional

Namespace name within the Account.

metadata.subnetstringOptional

Canonical subnet identifier where the workload should run.

Format Explicit scope or SDK placement

metadata.namestringRequired

Stable workload name within the namespace.

metadata.labelsmap[string]stringOptional

User-defined labels for grouping, filtering, and ownership metadata.

metadata.annotationsmap[string]stringOptional

User-defined annotations for descriptive metadata that is not used for identity.

specobjectRequired

Desired HostPodSet configuration.

spec.ownerstringRequired

Names whom the hosts serve. The platform treats it as an opaque label: it is set at creation and never changes. It is 1 to 128 characters of lowercase letters, digits, -, ., and /, beginning and ending with a letter or digit.

spec.controllerobjectOptional

The resource that controls this HostPodSet. It is set only at creation, only by a caller the platform authorizes as that controller, and never changes afterwards; the platform never adopts a HostPodSet by matching its name or labels. The hosts are served by the DaemonSet that carries the same controller.

spec.controller.kindstringRequired

Kind of the controlling resource, as its lowercase resource kind token.

Example supervisor

spec.controller.idstringRequired

ID of the controlling resource: the identity it keeps for its whole life.

Format Canonical UUID

spec.hostsobjectRequired

Desired host count and the bounds it must stay within.

spec.hosts.countintegerOptional

Number of hosts to keep placed, between min and max.

Default 0

spec.hosts.minintegerOptional

Fewest hosts the set may be scaled to. A value above zero is a warm reservation: that many hosts stay placed while they hold nothing.

Default 0

spec.hosts.maxintegerRequired

Most hosts the set may be scaled to.

Requirement At least 1

spec.strategyobjectRequired

Host replacement strategy.

spec.strategy.typestringRequired

Replacement strategy type.

Value RollingUpdate

spec.strategy.rollingUpdateobjectOptional

Rolling update controls. When omitted, the documented defaults of each control apply.

spec.strategy.rollingUpdate.maxUnavailableintegerOptional

Maximum number of hosts that may be out of service because of the replacement, counting a host while it drains.

Default 1

spec.strategy.rollingUpdate.maxSurgeintegerOptional

Maximum number of hosts that may be placed above the desired count while replacements are made.

Default 0

spec.templateobjectRequired

Template every host is made from.

spec.template.isolationstringRequired

Isolation class of the units the host holds.

Possible enum values:

container
secure-container
microvm

spec.template.gpuquantity stringOptional

GPU devices one host reserves for the units it holds.

Examples h100, 2:h100, nvidia:24Gi

spec.template.capacityobjectRequired

CPU and memory one host reserves.

spec.template.capacity.cpuquantity stringRequired

CPU one host reserves.

Examples 500m, 2

spec.template.capacity.memoryquantity stringRequired

Memory one host reserves.

Examples 512Mi, 4Gi

spec.template.placementobjectOptional

Restricts hosts to the nodes of one fleet inside the subnet. If omitted, a host may be placed on any eligible node of the subnet.

spec.template.placement.fleetstringRequired

Restricts placement to eligible members of this fleet.

Format 12-digit fleet ID

Read-only fields

IDYL can return these fields when you inspect a workload. Do not include them in authored manifests.

Field	Description
`metadata.id`	IDYL-assigned resource ID.
`metadata.namespace.id`	IDYL-assigned namespace ID.
`metadata.ownerReferences`	Parent workload relationship, such as a ReplicaSet owned by a Deployment.
`metadata.createdAt`	Creation timestamp.
`metadata.updatedAt`	Last update timestamp.
`metadata.deletedAt`	Deletion timestamp, when present.
`metadata.revision`	Revision information returned by IDYL.
`status`	Current observed state returned by IDYL.

Validation notes

kind values are case-sensitive.
At least one container is required in every pod spec.
At least one container must specify CPU or memory in resources.requests or resources.limits, unless the CLI fills those values from configured defaults before sending the workload.
GPU requirements belong at the pod spec gpu path, not under per-container resources.
Environment variable names must be unique within a container and must match [a-zA-Z_][a-zA-Z0-9_]*.

​Minimal manifest

​Example manifest

​Field reference

​Read-only fields

​Validation notes

Minimal manifest

Example manifest

Field reference

Read-only fields

Validation notes