Capsules

Overview

A capsule is a disposable container for one command or one shell. It is deleted when it exits. It is not a long-lived sandbox: that is a workspace. It has a file system, a toolchain, and a network. It has no effect on other workspaces.

A capsule runs one main process. You give the command at creation. The capsule ends when that process exits. Other processes can run inside the capsule, but the capsule waits only for the main one.

A capsule runs once. When it ends, its files are gone and it cannot start again. To run again, create a new capsule.

Each capsule has its own kernel, file system, and network stack, with allocated vCPU, memory, and disk. A capsule belongs to you or to a team that you are an active member of. Nobody else sees it. The platform gives it an id that starts with cap-.

Capsule types

A capsule is standalone or in a desk. The type is set at creation and does not change.

Sources

A capsule starts from one of three sources. The source decides what is in the capsule when it starts.

Creation parameters

The variables belong to the main process. A variable name uses letters, digits, and _, does not start with a digit, and is not HOME or KD_ followed by anything.

States

A capsule never stops and starts again. A create call returns at once with the phase pending. A fast command can end without the capsule being running.

The record also has exit_code, message (the cause of a failure), the times, the size, and the source.

Lifecycle

• Create. The call returns at once. The phase is pending, then starting, then running.
• Run. The hard lifetime counts from running and always applies. A capsule has no idle limit.
• In a desk. A capsule created through a desk is controlled through that desk. It ends when the desk is deleted. See Capsules.
• End. The main process exits, you end the capsule, or the time limit ends it. Its processes end and its files are gone.
• Record. The record of an ended capsule stays for 90 days. It shows the phase, the reason, the exit code, the output, the times, the size, and the source. A delete removes the record.

Adding packages to a running capsule

Inside a capsule, kd pkg add, kd pkg rm, kd pkg list, and kd pkg update change the packages of that capsule. The capsule does not restart, and its processes keep running. A new package is on PATH after the nix service answers, usually within seconds. kd pkg add jq followed by jq --version in the same shell works once the farm is rewritten.

The capsule holds a credential of its own for this, in KD_CAPSULE_TOKEN. It reaches the packages of that one capsule and nothing else, and it stops working when the capsule ends. A package that does not resolve is refused with a message, and the capsule keeps running with the packages it had.

Quota and limits

A running capsule counts its CPU, memory, and disk against the owner's quota. An ended capsule counts nothing. The capsules dimension of the quota limits how many capsules run at the same time.

Tasks

Create a capsule with a command

Reason for the task

Start an isolated machine that runs one command and ends with it.

Job set-up

• Access: you.
• References: POST /v1/capsules.

Procedure

1. Create the capsule with the command. The call returns at once.

   PythonCopy

   from kloudlite import Kodekl = Kloudlite()sb = kl.capsules.create(cmd=["python3", "main.py"], packages=["python3"], timeout_s=600)

   TypeScriptCopy

   import { Kode } from "./index.ts";const kl = new Kloudlite();const sb = await kl.capsules.create({ cmd: ["python3", "main.py"], packages: ["python3"], timeoutS: 600 });

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})sb, err := kl.Capsules.Create(kloudlite.CreateCapsule{Cmd: []string{"python3", "main.py"}, Packages: []string{"python3"}, Timeout: 600 * time.Second})if err != nil {    log.Fatal(err)}

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newsb = kl.capsules.create(cmd: ["python3", "main.py"], packages: ["python3"], timeout_s: 600)

   JavaCopy

   var kl = new Kloudlite();var sb = kl.capsules().create(new Kloudlite.CreateCapsule().cmd(List.of("python3", "main.py")).packages("python3").timeout(Duration.ofSeconds(600)));

   CLICopy

   kode capsules create --package python3 --timeout-s 600 -- python3 main.py

Close-out

1. Show the status as in task 002. Make sure that phase is pending, starting, running, or terminated.

Show the status of a capsule

Reason for the task

Read the phase of a capsule and, when it ended, the reason and the exit code.

Job set-up

• Access: you.
• References: GET /v1/capsules/{id}.

Procedure

1. Read the record of the capsule. The record shows the phase, the reason, the exit code, and the times.

   PythonCopy

   print(kl.capsules.get(capsule="cap-3c4d5e6f7a8b9c0d").doc)

   TypeScriptCopy

   console.log((await kl.capsules.get({ capsule: "cap-3c4d5e6f7a8b9c0d" })).doc);

   GoCopy

   got, err := kl.Capsules.Get("cap-3c4d5e6f7a8b9c0d")if err != nil {    log.Fatal(err)}fmt.Printf("%+v\n", got.CapsuleDoc)

   RubyCopy

   pp kl.capsules.get(capsule: "cap-3c4d5e6f7a8b9c0d").doc

   JavaCopy

   System.out.println(kl.capsules().get("cap-3c4d5e6f7a8b9c0d").json());

   CLICopy

   kode capsules get cap-3c4d5e6f7a8b9c0d

2. Wait until the capsule is running. The call fails with the reason when the capsule ends first.

   PythonCopy

   sb.wait_running(timeout_s=600)

   TypeScriptCopy

   await sb.waitRunning({ timeoutS: 600 });

   GoCopy

   if err := sb.WaitRunning(600 * time.Second); err != nil {    log.Fatal(err)}

   RubyCopy

   sb.wait_running(timeout_s: 600)

   JavaCopy

   sb.waitRunning(Duration.ofSeconds(600));

   CLICopy

   kode capsules wait-running cap-3c4d5e6f7a8b9c0d --timeout-s 600

Close-out

1. Make sure that the phase is running, or terminated with a reason. Make sure that exit_code is set when the reason is Exited.

Terminate a capsule and delete its record

Reason for the task

End a capsule before its command exits or its time limit, and release its resources.

Job set-up

• Access: you.
• Conditions: you have the handle sb. Use capsules.get with the id to get it.
• References: POST /v1/capsules/{id}/terminate, DELETE /v1/capsules/{id}.

Procedure

1. Terminate the capsule. The call is safe to repeat.

   PythonCopy

   sb.terminate()

   TypeScriptCopy

   await sb.terminate();

   GoCopy

   if err := sb.Terminate(); err != nil {    log.Fatal(err)}

   RubyCopy

   sb.terminate

   JavaCopy

   sb.terminate();

   CLICopy

   kode capsules terminate cap-3c4d5e6f7a8b9c0d

2. Wait until the capsule ends. The call returns the exit code, or no code when the process did not exit by itself.

   PythonCopy

   code = sb.wait()

   TypeScriptCopy

   const code = await sb.wait();

   GoCopy

   code, err := sb.Wait(0)if err != nil {    log.Fatal(err)}

   RubyCopy

   code = sb.wait

   JavaCopy

   int code = sb.waitFor(null);

   CLICopy

   kode capsules wait cap-3c4d5e6f7a8b9c0d

3. Delete the record if you do not need it.

   PythonCopy

   sb.delete()

   TypeScriptCopy

   await sb.delete();

   GoCopy

   if err := sb.Delete(); err != nil {    log.Fatal(err)}

   RubyCopy

   sb.delete

   JavaCopy

   sb.delete();

   CLICopy

   kode capsules delete cap-3c4d5e6f7a8b9c0d

Close-out

1. Make sure that reason is Terminated, or Exited when the command ended first.

List the run records

Reason for the task

Find the capsules of an owner and read why each one ended.

Job set-up

• Access: you.
• References: GET /v1/capsules, GET /v1/capsules/{id}.

Procedure

1. Show the capsules, newest first. Give a team to show only its capsules.

   PythonCopy

   for s in kl.capsules.list():    print(s.id, s.phase, s.reason)

   TypeScriptCopy

   for (const s of await kl.capsules.list()) {  console.log(s.id, s.phase, s.reason);}

   GoCopy

   capsules, err := kl.Capsules.List("")if err != nil {    log.Fatal(err)}for _, s := range capsules {    fmt.Println(s.ID, s.Phase, s.Reason)}

   RubyCopy

   kl.capsules.list.each do |s|  puts "#{s.id} #{s.phase} #{s.reason}"end

   JavaCopy

   for (var s : kl.capsules().list(null)) {    System.out.println(s.id() + " " + s.phase() + " " + s.reason());}

   CLICopy

   kode capsules list

Close-out

1. Make sure that each ended capsule shows the phase terminated, a reason, and its times.

Read the output and the exit code

Reason for the task

Read what the command printed and how it ended.

Job set-up

• Access: you.
• Conditions: you have the handle sb. Use capsules.get with the id to get it.
• References: GET /v1/capsules/{id}/logs, POST /v1/capsules/{id}/wait.

Procedure

1. Wait for the command to exit. The call returns the exit code.

   PythonCopy

   code = sb.wait()

   TypeScriptCopy

   const code = await sb.wait();

   GoCopy

   code, err := sb.Wait(0)if err != nil {    log.Fatal(err)}

   RubyCopy

   code = sb.wait

   JavaCopy

   int code = sb.waitFor(null);

   CLICopy

   kode capsules wait cap-3c4d5e6f7a8b9c0d

2. Read the output. Give follow to hold the call until the command ends.

   PythonCopy

   print(sb.logs())

   TypeScriptCopy

   console.log(await sb.logs());

   GoCopy

   out, err := sb.Logs(false)if err != nil {    log.Fatal(err)}fmt.Print(out)

   RubyCopy

   puts sb.logs

   JavaCopy

   System.out.print(sb.logs(false));

   CLICopy

   kode capsules logs cap-3c4d5e6f7a8b9c0d

Close-out

1. Make sure that the exit code is 0 and the output is the one that you expect.

Troubleshooting