Variables

Overview

A variable is a NAME=value pair that a resource gives to its processes. You set the variables of a workspace, a service, a capsule, 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 capsule documents do not return env.

Where you set variables

Parameters

A workspace and a capsule refuse the name HOME and each name that starts with KD_, 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.
• Capsule. 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, kode workspaces set-env.

Procedure

1. Send the complete list of variables.

   PythonCopy

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

   TypeScriptCopy

   import { Kode } 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

   kode 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}, kode 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.kode 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 capsule

Reason for the task

Give the main process of a capsule a set of variables.

Job set-up

• Access: you. A team capsule needs team membership.
• References: POST /v1/capsules, kode capsules create.

Procedure

1. Create the capsule with the variables in env.

   PythonCopy

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

   TypeScriptCopy

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

   GoCopy

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

   RubyCopy

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

   JavaCopy

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

   CLICopy

   kode capsules create --env MODE=test -- printenv MODE

Close-out

1. Read the output of the capsule 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, kode workspaces restart, kode environments restart.

Procedure

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

   PythonCopy

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

   TypeScriptCopy

   import { Kode } 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

   kode 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

   kode workspaces restart acme/apikode environments restart acme-dev --service api

Close-out

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

Troubleshooting