Skip to main content
A Job runs a pod template until the requested completions succeed.

​
Minimal manifest

kind: Job
metadata:
  name: import-data
  subnet: edge-a
spec:
  template:
    spec:
      restartPolicy: on_failure
      containers:
        - name: importer
          imageURI: ghcr.io/idyl-labs/importer:1.0.0
          resources:
            requests:
              cpu: 1
              memory: 1Gi

​
Example manifest

kind: Job
metadata:
  name: import-data
  subnet: edge-a
spec:
  completions: 10
  parallelism: 2
  backoffLimit: 3
  template:
    metadata:
      labels:
        job: import-data
    spec:
      restartPolicy: on_failure
      containers:
        - name: importer
          imageURI: ghcr.io/idyl-labs/importer:1.0.0
          args: ["--source", "s3://example/input"]
          resources:
            requests:
              cpu: 1
              memory: 1Gi
            limits:
              cpu: 2
              memory: 2Gi
              disk: 10Gi

​
Field reference

kindstringRequired

Resource kind. The value is case-sensitive.

Value Job

metadataobjectRequired

Top-level workload metadata.

metadata.namespaceobjectOptional

Optional namespace scope embedded in the manifest. CLI flags override these values.

Resolved from CLI context or flags can provide scope

metadata.namespace.accountIdstringOptional

Account that owns the namespace. The CLI can resolve this from context or —account-id.

Format 12-digit account ID

metadata.namespace.namespacestringOptional

Namespace name. The CLI can resolve this from context or —namespace.

metadata.subnetstringConditional

Subnet name or slug where the workload should run.

Resolved from —subnet or context can provide it

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 Job configuration.

spec.completionsintegerOptional

Number of successful pod completions required before the Job is complete.

spec.parallelismintegerOptional

Maximum number of pods the Job may run at the same time.

spec.backoffLimitintegerOptional

Number of failed pod attempts allowed before the Job is considered failed.

spec.templateobjectRequired

Pod template used by the Job.

spec.template.metadataobjectOptional

Metadata copied to pods created from this template.

spec.template.metadata.labelsmap[string]stringOptional

Labels copied to pods created from this template.

spec.template.metadata.annotationsmap[string]stringOptional

Annotations copied to pods created from this template.

spec.template.specobjectRequired

Pod spec used by this template.

spec.template.spec.restartPolicystringOptional

Container restart behavior.

Possible enum values:

  • always
  • on_failure
  • never
spec.template.spec.platformstringOptional

Platform identifies the workload OS and architecture. If omitted, IDYL resolves platform from policy and available capacity.

Possible enum values:

  • linux/amd64
  • linux/arm64
spec.template.spec.isolationobjectOptional

Isolation identifies the requested execution boundary. If omitted, IDYL resolves isolation from subnet policy.

Possible enum values:

  • container
  • microvm
spec.template.spec.isolation.classstringRequired

Class is the requested execution isolation boundary.

Possible enum values:

  • container
  • microvm
spec.template.spec.networkobjectOptional

Network identifies workload network intent. If omitted, the workload has no explicit network posture unless policy requires network intent.

Possible enum values:

  • none
  • restricted-egress
  • unrestricted
spec.template.spec.network.classstringRequired

Class is the requested workload network policy.

Possible enum values:

  • none
  • restricted-egress
  • unrestricted
spec.template.spec.network.egressobjectOptional

Egress defines allowed outbound destinations for restricted-egress workloads.

Format Restricted egress allow rules

spec.template.spec.network.egress.allowarray[string]Optional

Allow contains structured allow rules such as “dns” or “tcp:443:api.example.com”. TCP targets must be DNS hostnames, not IP literals.

Possible enum values:

  • dns
  • tcp:<port>:<dns-hostname>
spec.template.spec.network.egress.denyLocalNetworksbooleanOptional

DenyLocalNetworks must be true when network.egress.allow is set. Local networks remain denied while the listed destinations are allowed.

Value true

spec.template.spec.gpuquantity stringOptional

Pod-level GPU requirement. GPU is a physical host device requirement, not a per-container resource. All containers in the pod share GPU access.

Examples h100, 2:h100, nvidia:24Gi

spec.template.spec.requiremap[string]stringOptional

Require specifies host-level capability requirements (e.g., cuda: ”>=13.0”). Pods will only be scheduled on nodes that satisfy all requirements.

Format Exact version or >= minimum version

spec.template.spec.containersarrayRequired

Containers that run in the pod.

Requirement At least one container

spec.template.spec.containers[].namestringRequired

Container name, unique within the pod.

spec.template.spec.containers[].imageURIstringRequired

Container image reference, such as nginx:latest, ubuntu:22.04, or a private registry image.

spec.template.spec.containers[].imageDigeststringOptional

ImageDigest is the optional digest for image verification (e.g., “sha256:abc123…”) When provided, it’s appended to registry images as “image@sha256:abc123”

Example sha256:…

spec.template.spec.containers[].imagePullPolicystringOptional

When the runtime should pull the image.

Possible enum values:

  • always
  • never
  • if_not_present
spec.template.spec.containers[].imagePullCredentialsobjectOptional

ImagePullCredentials specifies credentials for pulling from private registries. If nil, no authentication is used (public registry or pre-configured daemon auth).

spec.template.spec.containers[].imagePullCredentials.usernamestringOptional

Username for registry authentication (e.g., “AWS” for ECR, “_json_key” for GCR)

spec.template.spec.containers[].imagePullCredentials.passwordstringOptional

Password or token for registry authentication

spec.template.spec.containers[].commandarray[string]Optional

Command overrides the container image’s ENTRYPOINT. If empty, the image’s default ENTRYPOINT is used. If set without Args, the image’s default CMD is still used with the new entrypoint.

spec.template.spec.containers[].argsarray[string]Optional

Args overrides the container image’s CMD. If empty, the image’s default CMD is used.

spec.template.spec.containers[].envarrayOptional

Env is a list of environment variables to set in the container.

spec.template.spec.containers[].env[].namestringRequired

Environment variable name.

Pattern [a-zA-Z_][a-zA-Z0-9_]*

spec.template.spec.containers[].env[].valuestringRequired

Environment variable value.

spec.template.spec.containers[].resourcesobjectConditional

Container resource requests and limits.

Requirement CPU or memory must be set on at least one container

spec.template.spec.containers[].resources.requestsobjectOptional

Resources used for scheduling. If a request is omitted but a limit is set for that resource, the limit is used as the effective request.

spec.template.spec.containers[].resources.requests.cpuquantity stringOptional

CPU quantity for this resource entry.

Examples 500m, 0.5, 1

spec.template.spec.containers[].resources.requests.memoryquantity stringOptional

Memory quantity for this resource entry.

Examples 256Mi, 1Gi

spec.template.spec.containers[].resources.requests.diskquantity stringOptional

Disk quantity for this resource entry.

Examples 1Gi, 10G

spec.template.spec.containers[].resources.limitsobjectOptional

Maximum resources allowed for the container.

spec.template.spec.containers[].resources.limits.cpuquantity stringOptional

CPU quantity for this resource entry.

Examples 500m, 0.5, 1

spec.template.spec.containers[].resources.limits.memoryquantity stringOptional

Memory quantity for this resource entry.

Examples 256Mi, 1Gi

spec.template.spec.containers[].resources.limits.diskquantity stringOptional

Disk quantity for this resource entry.

Examples 1Gi, 10G

spec.template.spec.sharedVolumeSizequantity stringOptional

Size of the shared volume mounted for the pod.

Format Memory/disk units

​
Read-only fields

IDYL can return these fields when you inspect a workload. Do not include them in authored manifests.
FieldDescription
metadata.idIDYL-assigned resource ID.
metadata.namespace.idIDYL-assigned namespace ID.
metadata.subnetSlugResolved subnet slug returned by IDYL.
metadata.ownerReferencesParent workload relationship, such as a ReplicaSet owned by a Deployment.
metadata.createdAtCreation timestamp.
metadata.updatedAtLast update timestamp.
metadata.deletedAtDeletion timestamp, when present.
metadata.revisionRevision information returned by IDYL.
statusCurrent 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_]*.