Variables

Description and operation

General

A variable is a NAME=value environment variable that a resource gives to its processes. You set the variables of a workspace, a service, a sandbox or a pipeline job in its env field. The value is stored in plain text in the definition of the resource. Use a secret for a password, a key or a token.

A value that is exactly ${{ secrets.NAME }} is a reference: the variable gets the value of that secret instead. See Reference syntax.

The variables belong to the resource, and its owner sets them. The environment document returns the variables of each service. The workspace and sandbox documents do not return env.

Where you set variables

Parameters

A workspace and a sandbox refuse the name HOME and each name that starts with KL_, because the platform sets them.

Lifecycle

• Set. A call that sets env replaces the whole map. A variable that is not in the new map is removed.
• Workspace. A new env reaches the processes at the next start. A running workspace keeps the variables that it has.
• Service. A new env reaches the service at its next start. A running service keeps the variables that it has.
• Restart required. A running workspace or service with old variables shows restart_required. The message names the changed variables and never shows a value. A start for any cause gives the current variables and removes the mark. See Restart to apply new variables.
• Automatic restart. Set restartOnEnvChange to true to restart the resource when its variables change. The default is false.
• Sandbox. The variables are set at creation and do not change.
• Pipeline job. A step gets the env of the job, with the env of the step over it.
• Clone and restore. A clone or a restore of a workspace has no variables. Set them again on the new workspace.

Quota and limits

Variables do not count against the quota of the owner.

Tasks

Set the variables of a workspace

Reason for the task: Give the processes of a workspace a set of variables.

Job set-up

• Access: you. Only the owner of the workspace can set its variables.
• References: PUT /v1/workspaces/{id}/env, kloudlite workspaces set-env.

Procedure

1. Send the complete list of variables.

   PythonCopy

   from kloudlite import Kloudlitekl = Kloudlite()kl.workspaces.set_env(workspace="acme/api", env={"LOG_LEVEL": "debug", "PORT": "3000"})

   TypeScriptCopy

   import { Kloudlite } from "./index.ts";const kl = new Kloudlite();await kl.workspaces.setEnv({ workspace: "acme/api", env: { LOG_LEVEL: "debug", PORT: "3000" } });

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})if _, err := kl.Workspaces.SetEnv("acme/api", map[string]string{"LOG_LEVEL": "debug", "PORT": "3000"}); err != nil {    log.Fatal(err)}

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newkl.workspaces.set_env(workspace: "acme/api", env: { "LOG_LEVEL" => "debug", "PORT" => "3000" })

   JavaCopy

   var kl = new Kloudlite();kl.workspaces().setEnv("acme/api", Map.of("LOG_LEVEL", "debug", "PORT", "3000"));

   CLICopy

   kloudlite workspaces set-env acme/api --env LOG_LEVEL=debug --env PORT=3000

2. Send a restart for the workspace. See Restart to apply new variables.

Close-out

1. Run printenv LOG_LEVEL in the workspace. Make sure that the output is debug.

Set the variables of a service

Reason for the task: Give a service of an environment a set of variables.

Job set-up

• Access: you. A team environment needs team membership.
• Conditions: the service exists. See Add a service.
• References: PATCH /v1/environments/{id}, kloudlite environments set-services.

Procedure

1. Send the service list with the new env of the service, here api.

   PythonCopy

   env = kl.environments.get(environment="acme-dev")services = [{**sv, "env": {**sv["env"], "LOG_LEVEL": "debug"}} if sv["name"] == "api" else sv for sv in env["services"]]kl.environments.set_services(environment="acme-dev", services=services)

   TypeScriptCopy

   import { type Service } from "./index.ts";const env = (await kl.environments.get({ environment: "acme-dev" })) as { services: Service[] };const services = env.services.map((sv) => (sv.name === "api" ? { ...sv, env: { ...sv.env, LOG_LEVEL: "debug" } } : sv));await kl.environments.setServices({ environment: "acme-dev", services });

   GoCopy

   env, err := kl.Environments.Get("acme-dev")if err != nil {    log.Fatal(err)}var services []kloudlite.Serviceraw, _ := json.Marshal(env["services"])if err := json.Unmarshal(raw, &services); err != nil {    log.Fatal(err)}for i := range services {    if services[i].Name == "api" {        if services[i].Env == nil {            services[i].Env = map[string]string{}        }        services[i].Env["LOG_LEVEL"] = "debug"    }}if err := kl.Environments.SetServices(kloudlite.SetServices{Environment: "acme-dev", Services: services}); err != nil {    log.Fatal(err)}

   RubyCopy

   env = kl.environments.get(environment: "acme-dev")services = env["services"].map do |sv|  sv["name"] == "api" ? sv.merge("env" => sv["env"].merge("LOG_LEVEL" => "debug")) : svendkl.environments.set_services(environment: "acme-dev", services: services)

   JavaCopy

   // Replaces the list: describe every service, with the new variable in api.var api = new Kloudlite.Service().name("api").image("ghcr.io/acme/api:1.0").port(8080)    .env("LOG_LEVEL", "debug");kl.environments().setServices(new Kloudlite.SetServices().environment("acme-dev").services(api));

   CLICopy

   # Replaces the list: send every service, with the new variable in api.kloudlite environments set-services acme-dev --services '[  {"name": "api", "image": "ghcr.io/acme/api:1.0", "ports": [8080], "env": {"LOG_LEVEL": "debug"}}]'

2. Send a restart for the service. See Restart to apply new variables.

Close-out

1. Get the environment again. Make sure that api shows the new env and that service_status shows it as ready.

Set the variables of a sandbox

Reason for the task: Give the main process of a sandbox a set of variables.

Job set-up

• Access: you. A team sandbox needs team membership.
• References: POST /v1/sandboxes, kloudlite sandboxes create.

Procedure

1. Create the sandbox with the variables in env.

   PythonCopy

   sb = kl.sandboxes.create(cmd=["printenv", "MODE"], env={"MODE": "test"})

   TypeScriptCopy

   const sb = await kl.sandboxes.create({ cmd: ["printenv", "MODE"], env: { MODE: "test" } });

   GoCopy

   sb, err := kl.Sandboxes.Create(kloudlite.CreateSandbox{Cmd: []string{"printenv", "MODE"}, Env: map[string]string{"MODE": "test"}})if err != nil {    log.Fatal(err)}

   RubyCopy

   sb = kl.sandboxes.create(cmd: ["printenv", "MODE"], env: { "MODE" => "test" })

   JavaCopy

   var sb = kl.sandboxes().create(new Kloudlite.CreateSandbox().cmd(List.of("printenv", "MODE")).env(Map.of("MODE", "test")));

   CLICopy

   kloudlite sandboxes create --env MODE=test -- printenv MODE

Close-out

1. Read the output of the sandbox as in Read the output and the exit code. Make sure that the output is test.

Set the variables of a pipeline job

Reason for the task: Give the steps of a pipeline job a set of variables.

Job set-up

• Access: you. For a team, an admin.
• References: Pipeline definition.

Procedure

1. Add env to the job. Each step of the job gets these variables.

   jsonCopy

   { "jobs": { "test": { "env": { "LOG_LEVEL": "debug" } } } }

2. Add env to a step to add a variable, or to replace one of the job, for that step only.

   jsonCopy

   { "steps": [{ "run": "./test.sh", "env": { "LOG_LEVEL": "trace" } }] }

3. Send the definition as the next version of the pipeline.

Close-out

1. Start a run and read the log. Make sure that the job starts with the variables.

Restart to apply new variables

Reason for the task: Give a running workspace or service the variables and secret values that changed since it started.

Job set-up

• Access: you. A team resource needs team membership.
• Conditions: the workspace or the environment runs. The resource shows restart_required.
• References: POST /v1/workspaces/{id}/restart, POST /v1/environments/{id}/services/{service}/restart, kloudlite workspaces restart, kloudlite environments restart.

Procedure

1. Read which variables changed. The message names them and never shows a value.

   PythonCopy

   from kloudlite import Kloudlitekl = Kloudlite()print(kl.workspaces.get(workspace="acme/api").get("restart_required"))

   TypeScriptCopy

   import { Kloudlite } from "./index.ts";const kl = new Kloudlite();console.log(((await kl.workspaces.get({ workspace: "acme/api" })) as { restart_required?: unknown }).restart_required);

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})ws, err := kl.Workspaces.Get("acme/api")if err != nil {    log.Fatal(err)}fmt.Println(ws["restart_required"])

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newputs kl.workspaces.get(workspace: "acme/api")["restart_required"]

   JavaCopy

   var kl = new Kloudlite();System.out.println(kl.workspaces().get("acme/api"));

   CLICopy

   kloudlite workspaces get acme/api

2. Send a restart for the workspace, or for the one service of the environment, here api of acme-dev.

   PythonCopy

   kl.workspaces.restart(workspace="acme/api")kl.environments.restart(environment="acme-dev", service="api")

   TypeScriptCopy

   await kl.workspaces.restart({ workspace: "acme/api" });await kl.environments.restart({ environment: "acme-dev", service: "api" });

   GoCopy

   if err := kl.Workspaces.Restart("acme/api"); err != nil {    log.Fatal(err)}if err := kl.Environments.Restart("acme-dev", "api"); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.workspaces.restart(workspace: "acme/api")kl.environments.restart(environment: "acme-dev", service: "api")

   JavaCopy

   kl.workspaces().restart("acme/api");kl.environments().restart("acme-dev", "api");

   CLICopy

   kloudlite workspaces restart acme/apikloudlite environments restart acme-dev --service api

Close-out

1. Get the resource again. Make sure that it does not show restart_required.

Troubleshooting