The Workload Spec

A workload is a resource of the kind vantacloud/workload, written at /v1/orgs/{org}/vantacloud/workloads/{name} through the platform API. The spec is the one declaration every compute target takes: a cluster of your organization, or a swarm placing it on a cluster, a VM or a machine.

An example

kind: vantacloud/workload
name: api
labels:
  app: shop
spec:
  target:
    cluster: prod-eu
  containers:
    - name: api
      image: shop/api:1.4.2
      args: ["--port", "8080"]
      env:
        LOG_LEVEL: info
      ports:
        - name: http
          port: 8080
      resources:
        cpu: 500m
        memory: 512Mi
      readiness:
        httpGet:
          path: /healthz
          port: http
  scaling:
    min: 2
    max: 6
    targetCpuPercent: 70
  capabilities:
    db:
      - resource: vantadb/instance/main
        operations: [connect]
        scope: app
    vault:
      - resource: vantacrypt/secret/payments
        operations: [use]
    telemetry: {}
  observability:
    service: shop-api
    conventions: "1"
    probes:
      - name: http
        kind: http
        port: http
        path: /healthz
        boundMilliseconds: 300
    notify:
      emails: [[email protected]]

Fields

Field	Holds
target	Where the workload runs: cluster, a cluster of your organization, or swarm, a swarm of it, one of the two
containers	One or more containers, the first the primary
containers[].name	The container’s name, a DNS label unique in the workload
containers[].image	The image, <registry>/<repository>:<tag> or @<digest>, from a registry of your organization’s or a public registry; a tag is pinned to its digest when the spec is written
containers[].command, containers[].args	The entrypoint and its arguments, the image’s when absent
containers[].env	Environment variables as literal string pairs
containers[].ports	Each port’s name, a DNS label, port and protocol, tcp or udp, tcp when absent
containers[].resources	cpu, in cores or millicores, memory, in bytes with a binary suffix, and gpu, a count of whole devices, 0 when absent; cpu and memory are both the request and the limit
containers[].readiness, containers[].liveness	A probe the replica’s own lifecycle reads, httpGet with path and port or tcp with port, with periodSeconds and failureThreshold, 10 and 3 when absent
containers[].mounts	Each mount’s volume, a volume of the spec, path and readOnly
volumes	Each volume’s name and its kind: ephemeral, discarded with the replica, or persistent with its size, one per replica, kept across restarts
scaling	replicas, a fixed count, or min, max and targetCpuPercent; 1 replica when absent
update	maxUnavailable, how many replicas a rollout may take down at once, 0 when absent; at least 1 for a workload with a persistent volume
capabilities	A map from capability to its grants, each grant’s resource, operations and scope; models, accounts, vantanet and telemetry take an empty object
observability	The workload’s telemetry profile, its uptime probes and its alert targets, stated below; required
placement	For a swarm target: labels a member carries, provider and region a member is on, and spread, whether replicas spread across members or pack onto as few as fit

A spec names no secret. A credential your workload needs is a grant of the vault capability, and a value your containers read is an environment variable or a file of your image.

Observability

The observability block is required, and a new spec or a change to one without it, without a probe or without the telemetry capability is refused with invalid-argument naming the field. A spec stored without the block keeps running, is shown non-conformant with the reason “no observability block” and gets no probes, dashboard or default alerts until its next change, which carries the block.

Field	Holds
service	The service.name your telemetry reports under, a DNS label
conventions	The version of the telemetry conventions your code reports by, "1"
probes	One or more uptime probes, below
ackBoundMilliseconds	The bound the latency alert holds every operation’s ack to, from 50 to 10,000, 300 when absent
notify	Where the default alerts notify: emails, addresses, and webhooks, HTTPS URLs, at least one target across the two

Each probe is a request the platform sends your workload on an interval, from beside it, and the answer it expects.

Field	Holds
name	The probe’s name, a DNS label unique in the workload, which its series carry
kind	http, an HTTP request expecting status; tcp, a connection expecting it accepted; or stun, one STUN Binding request over UDP expecting a Binding success response
port	A port of the primary container, by name, a udp one for stun
method	For http, GET or HEAD, GET when absent
path	For http, the path requested; required
status	For http, the status the answer must carry, 200 when absent
boundMilliseconds	The latency bound, from 50 to 10,000, 300 when absent; an answer arriving later counts as a failure
intervalSeconds	How often the probe is sent, from 5 to 300, 15 when absent

A readiness or liveness probe decides when a replica is restarted or taken out of service. An uptime probe decides whether your workload is up, and neither replaces the other. Point the uptime probe at a path that exercises what your callers depend on, within its bound, and answers fast.

Calls on a running workload

Call	Does
POST /v1/orgs/{org}/vantacloud/workloads/{name}/restart	Restarts every replica by a rolling restart
POST /v1/orgs/{org}/vantacloud/workloads/{name}/rollback	Writes the previous generation’s spec as a new generation
GET /v1/orgs/{org}/vantacloud/workloads/{name}/replicas	Answers each replica’s name, member, phase, restarts and image digest

A workload’s status carries replicas with the desired, ready and updated counts and the conditions Ready, Progressing and Admitted. Its logs, metrics and uptime are read on the terms Reading Your Telemetry states.