Guides / Compute
Run a program as a process
Once you have built a program, this guide gets it running. You register the program once and then run it as one or more processes. Each process has its own interfaces on your VPCs, its own settings and its own state.
1. Register the program
In the console, open Compute, then Program, choose New, name it and pick the .wasm file. With kubectl, pass the module as base64 text:
kubectl apply -f - <<EOF
apiVersion: compute.etorm.com/v1alpha1
kind: Program
metadata: {name: reflector}
spec:
module: $(base64 < reflector.wasm | tr -d '\n')
EOF
The module is checked when you register it, and a refusal names the reason, for example an import that does not exist. A registered program cannot be changed. To change the code, register a new program under a new name. Check that it was accepted:
kubectl get program reflector # NAME DIGEST SIZE PHASE # reflector sha256:3c1f… 395 Ready
2. Start a process
A process names a program and gives it up to 8 interfaces. Each interface is a port on a VPC.
apiVersion: compute.etorm.com/v1alpha1
kind: Process
metadata: {name: echo}
spec:
programRef: {name: reflector}
interfaces:
- {name: eth0, vpcRef: {name: lan}}
config: {greeting: hello} # read by the program with host.config
resources:
memoryPower: 0 # memory: 64 KiB x 2^n (0 = 64 KiB, 1 = 128 KiB, 4 = 1 MiB, ... 12 = 256 MiB)
cpuMillicores: 100 # processor time on average: 100 = a tenth of a core
cpuShare: 10 # relative weight when processes compete (1 to 100)
stateMaxBytes: 65536
restartPolicy: Always
Choose its memory and processor time
Every process has a memory allowance and a processor allowance. Both have defaults, and no process can use more than it was given.
| Field | Meaning |
|---|---|
resources.memoryPower | Memory is 64 KiB times two to the power of this number: 0 is 64 KiB, 1 is 128 KiB, 2 is 256 KiB, 3 is 512 KiB, 4 is 1 MiB (the default), up to 12 which is 256 MiB. A program that needs more when it starts is refused, and the message names the power that fits. If it asks for more memory while running than it is allowed, that activation fails. |
resources.cpuMillicores | Processor time on average, in thousandths of one core: 100 (the default) is a tenth of a core, 1000 a whole core. Short bursts above it are fine; once the burst is used up the work waits until the allowance has recovered, and status.usage.throttled counts how often that happened. |
status.memory and status.cpu show the allowances in words. A program that fits in one 64 KiB page, like the reflector, can run at memoryPower: 0.
3. Read its phase and addresses
kubectl get process echo -o jsonpath='{.status.phase}{"\n"}'
kubectl get process echo -o jsonpath='{.status.interfaces}'
Each interface gets a MAC address that starts with 02:e8: and stays the same for as long as the interface exists. It also gets a link-local address, and the address SLAAC would form from that MAC in the VPC's IPv6 prefix. These are the addresses the platform reports, but the program may use any address it likes. IPv4 is optional and is never assigned for you.
| Phase | Meaning |
|---|---|
Pending | Waiting. The condition says why: ProgramNotReady, VpcNotReady or NoNode (no machine runs it). |
Ready | Placed and running. A process with nothing to do is still Ready. |
Suspended | spec.desiredState: Suspended: it keeps its state and interfaces and receives nothing. |
Stopped | spec.desiredState: Stopped: its state is deleted. |
Failed | Five activations in a row failed. status.usage.lastError says why. |
status.usage counts activations, failures, fuel, frames in and out and frames dropped, and status.logs holds the last 50 lines the program logged. Both refresh about every 30 seconds.
Keep memory between wake-ups, and use buckets
spec.residency: Residentkeeps the program's instance, and so its memory, between wake-ups. Use it for programs that hold connections or caches. A resident process still uses only its memory and processor allowance. A failure or a restart begins it again, and then itsstatesurvives but its memory does not.spec.bucketslists up to four buckets of the project that the program may read and write through the object interface (get, put, create-only put, delete). Any other bucket is refused.
Suspend, change or replace a process
- To suspend and resume a process, set
spec.desiredState. The program'sstophandler runs first, and then frames are no longer delivered. On resume the process starts a new life, and timers that came due fire once. - To change the program or its settings, edit the process. A new program name, config, interfaces or schedules start a new life. The saved state is kept.
- Add and remove interfaces as whole entries. To rename one, remove it and add the new name.
If it stays Pending
- If the program is
Failed,kubectl get program NAME -o jsonpath='{.status.conditions}'names the problem. - If the process stays
Pending/NoNodefor long, no machine is attached to run it. A process runs where its VPCs are served. - If frames are dropped, the program is too slow for the traffic, or it never returns from
frames. Checkstatus.usageandstatus.logs.
See also Find out why something stays Pending.
Clean up
kubectl delete process echo kubectl delete program reflector
Deleting a process deletes its state and stops its metering. Delete the processes before the program. Nothing stops you deleting a program that is still in use, and its processes then stay Pending with reason ProgramNotReady. There is more in Delete things safely.