Secrets

Description and operation

General

A secret is a named value in a secret store. There is one store for you, one for each team, and one for you in each team that you are a member of. The name is the key in that store. A value goes into the store and never comes out: no call, list or log returns it. A resource uses a secret through a reference. See Env Vars.

You manage secrets with kloudlite secrets (alias kloudlite secret), the SDK or the API. The CLI reads the value only from standard input, never from an argument, because other processes and the shell history can read an argument. It removes one trailing line break, and it refuses an empty value.

Your secrets in a team are for your own resources in that team. See Personal secrets in a team.

Parameters

Lifecycle

• Set. A new name adds a secret. The owner then has it for all its resources. Your secret in a team is for your own resources in that team only.
• Replace. Setting an existing name replaces its value. A workspace or a service that uses the secret gets the new value at its next start. Until then, it shows restart_required. See When a new value takes effect.
• Delete. A delete is refused with 409 while a workspace, a sandbox or a service of the owner refers to the secret. The message names each one. A pipeline also stops the delete when its newest version, or a queued or running run, refers to the secret.
• Delete your secret in a team. A delete is refused with 409 while your resource in the team refers to the name, and the team has no such secret. When the team has the name, the reference reads the secret of the team.
• Removed owner. When a team is deleted, its secrets and the secrets of its members in it are deleted. When you leave a team, your secrets in it are deleted after 7 days. If you join again in that time, they are kept.

Quota and limits

Tasks

Set or replace a secret

Reason for the task: Store a value under a name, or change the value of an existing secret.

Job set-up

• Access: you. For a secret of the team, a team member with the role admin or higher.
• References: PUT /v1/secrets/{owner}/{name}, kloudlite secrets set.

Procedure

1. Read the value into the shell variable DB_URL. The terminal does not show what you type.

   CLICopy

   read -rs DB_URL && export DB_URL

2. Send the value of the secret DB_URL of the team acme. For your own secret, use your handle and no scope.

   PythonCopy

   import osfrom kloudlite import Kloudlitekl = Kloudlite()kl.secrets.set(owner="acme", name="DB_URL", value=os.environ["DB_URL"], scope="team")

   TypeScriptCopy

   import { Kloudlite } from "./index.ts";const kl = new Kloudlite();await kl.secrets.set({ owner: "acme", name: "DB_URL", value: process.env.DB_URL!, scope: "team" });

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})if err := kl.Secrets.Set("acme", "DB_URL", os.Getenv("DB_URL"), kloudlite.SecretOptions{Scope: "team"}); err != nil {    log.Fatal(err)}

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newkl.secrets.set(owner: "acme", name: "DB_URL", value: ENV.fetch("DB_URL"), scope: "team")

   JavaCopy

   var kl = new Kloudlite();kl.secrets().set("acme", "DB_URL", System.getenv("DB_URL"), "team");

   CLICopy

   printf %s "$DB_URL" | kloudlite secrets set DB_URL --owner acme --scope team

3. Remove the value from the shell.

   CLICopy

   unset DB_URL

Close-out

1. Show the secrets as in task 002. Make sure that DB_URL shows the time of this change.

Show the secrets

Reason for the task: Find the names of the secrets of an owner, and who changed each one and when.

Job set-up

• Access: you. For a team, a team member whose access is not paused.
• References: GET /v1/secrets/{owner}, kloudlite secrets list.

Procedure

1. Show the names of the secrets of the team acme. The list never holds a value.

   PythonCopy

   for s in kl.secrets.list(owner="acme", scope="team"):    print(s["name"], s["updated_at"], s["updated_by"])

   TypeScriptCopy

   for (const s of await kl.secrets.list({ owner: "acme", scope: "team" })) {  console.log(s.name, s.updated_at, s.updated_by);}

   GoCopy

   secrets, err := kl.Secrets.List("acme", kloudlite.SecretOptions{Scope: "team"})if err != nil {    log.Fatal(err)}for _, s := range secrets {    fmt.Println(s["name"], s["updated_at"], s["updated_by"])}

   RubyCopy

   kl.secrets.list(owner: "acme", scope: "team").each do |s|  puts "#{s["name"]} #{s["updated_at"]} #{s["updated_by"]}"end

   JavaCopy

   System.out.println(kl.secrets().list("acme", "team"));

   CLICopy

   kloudlite secrets list --owner acme --scope team

Close-out

1. Read the output. The CLI shows none for an owner with no secret.

Delete a secret

Reason for the task: Remove a secret that nothing uses.

Job set-up

• Access: you. For a secret of the team, a team member with the role admin or higher.
• Conditions: no workspace, sandbox, service or pipeline of the owner refers to the secret.
• References: DELETE /v1/secrets/{owner}/{name}, kloudlite secrets delete.

Procedure

1. Delete the secret DB_URL of the team acme.

   PythonCopy

   kl.secrets.delete(owner="acme", name="DB_URL", scope="team")

   TypeScriptCopy

   await kl.secrets.delete({ owner: "acme", name: "DB_URL", scope: "team" });

   GoCopy

   if err := kl.Secrets.Delete("acme", "DB_URL", kloudlite.SecretOptions{Scope: "team"}); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.secrets.delete(owner: "acme", name: "DB_URL", scope: "team")

   JavaCopy

   kl.secrets().delete("acme", "DB_URL", "team");

   CLICopy

   kloudlite secrets delete DB_URL --owner acme --scope team

Close-out

1. Show the secrets as in task 002. Make sure that DB_URL is not in the list.

Set a personal secret in a team

Reason for the task: Keep your own value, such as an access token, for your resources in a team.

Job set-up

• Access: you, as an active member of the team.
• References: PUT /v1/secrets/{owner}/mine/{name}, kloudlite secrets set.

Procedure

1. Read the value into the shell variable GITHUB_TOKEN. The terminal does not show what you type.

   CLICopy

   read -rs GITHUB_TOKEN && export GITHUB_TOKEN

2. Send the value. This example sets your secret GITHUB_TOKEN in the team acme.

   PythonCopy

   import osfrom kloudlite import Kloudlitekl = Kloudlite()kl.secrets.set(owner="acme", name="GITHUB_TOKEN", value=os.environ["GITHUB_TOKEN"])

   TypeScriptCopy

   import { Kloudlite } from "./index.ts";const kl = new Kloudlite();await kl.secrets.set({ owner: "acme", name: "GITHUB_TOKEN", value: process.env.GITHUB_TOKEN! });

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})if err := kl.Secrets.Set("acme", "GITHUB_TOKEN", os.Getenv("GITHUB_TOKEN")); err != nil {    log.Fatal(err)}

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newkl.secrets.set(owner: "acme", name: "GITHUB_TOKEN", value: ENV.fetch("GITHUB_TOKEN"))

   JavaCopy

   var kl = new Kloudlite();kl.secrets().set("acme", "GITHUB_TOKEN", System.getenv("GITHUB_TOKEN"));

   CLICopy

   printf %s "$GITHUB_TOKEN" | kloudlite secrets set GITHUB_TOKEN --owner acme

3. Remove the value from the shell.

   CLICopy

   unset GITHUB_TOKEN

Close-out

1. Show your secrets in the team as in task 005. Make sure that GITHUB_TOKEN shows the time of this change.

Show your personal secrets in a team

Reason for the task: Find the names of your own secrets in a team.

Job set-up

• Access: you, as an active member of the team.
• References: GET /v1/secrets/{owner}/mine, kloudlite secrets list.

Procedure

1. Show the names. The list holds only your names, and never a value.

   PythonCopy

   for s in kl.secrets.list(owner="acme"):    print(s["name"], s["updated_at"], s["updated_by"])

   TypeScriptCopy

   for (const s of await kl.secrets.list({ owner: "acme" })) {  console.log(s.name, s.updated_at, s.updated_by);}

   GoCopy

   secrets, err := kl.Secrets.List("acme")if err != nil {    log.Fatal(err)}for _, s := range secrets {    fmt.Println(s["name"], s["updated_at"], s["updated_by"])}

   RubyCopy

   kl.secrets.list(owner: "acme").each do |s|  puts "#{s["name"]} #{s["updated_at"]} #{s["updated_by"]}"end

   JavaCopy

   System.out.println(kl.secrets().list("acme"));

   CLICopy

   kloudlite secrets list --owner acme

Close-out

1. Read the output. The CLI shows none when you have no secret in the team.

Delete a personal secret in a team

Reason for the task: Remove your own secret in a team.

Job set-up

• Access: you, as an active member of the team.
• Conditions: none of your resources in the team refers to the name, or the team has a secret of that name.
• References: DELETE /v1/secrets/{owner}/mine/{name}, kloudlite secrets delete.

Procedure

1. Delete your secret GITHUB_TOKEN in the team acme.

   PythonCopy

   kl.secrets.delete(owner="acme", name="GITHUB_TOKEN")

   TypeScriptCopy

   await kl.secrets.delete({ owner: "acme", name: "GITHUB_TOKEN" });

   GoCopy

   if err := kl.Secrets.Delete("acme", "GITHUB_TOKEN"); err != nil {    log.Fatal(err)}

   RubyCopy

   kl.secrets.delete(owner: "acme", name: "GITHUB_TOKEN")

   JavaCopy

   kl.secrets().delete("acme", "GITHUB_TOKEN");

   CLICopy

   kloudlite secrets delete GITHUB_TOKEN --owner acme

Close-out

1. Show your secrets in the team as in task 005. Make sure that GITHUB_TOKEN is not in the list.

Troubleshooting