Skip to main content

Built-in Functions

sloth-kubernetes configuration files use a LISP dialect with powerful built-in functions for dynamic configuration generation.

Environment Functions​

env / getenv​

Get environment variable value.

(env "DIGITALOCEAN_TOKEN")
(env "MY_VAR" "default-value")  ; with fallback
(getenv "AWS_REGION")           ; alias for env

env-or​

Get environment variable with required fallback.

(env-or "DATABASE_URL" "postgres://localhost:5432/mydb")

env?​

Check if environment variable exists.

(if (env? "PRODUCTION")
    (size "s-4vcpu-8gb")
    (size "s-1vcpu-1gb"))

String Functions​

concat / str​

Concatenate strings.

(concat "prefix-" (env "CLUSTER_NAME") "-suffix")
(str "node-" "1")  ; alias for concat

format​

Format string with placeholders (Printf-style).

(format "%s-cluster-%d" "production" 1)
; Result: "production-cluster-1"

upper / lower​

Convert string case.

(upper "hello")  ; "HELLO"
(lower "WORLD")  ; "world"

trim​

Remove leading/trailing whitespace.

(trim "  hello  ")  ; "hello"

split​

Split string into list.

(split "a,b,c" ",")  ; ("a" "b" "c")

join​

Join list into string.

(join (list "a" "b" "c") ",")  ; "a,b,c"

replace​

Replace all occurrences in string.

(replace "hello-world" "-" "_")  ; "hello_world"

substring​

Extract substring.

(substring "hello" 0 3)  ; "hel"
(substring "hello" 2)    ; "llo" (to end)

Control Flow​

if​

Conditional expression.

(if (env? "PRODUCTION")
    "s-4vcpu-8gb"
    "s-1vcpu-1gb")

when​

Execute body when condition is true.

(when (env? "ENABLE_GPU")
  (gpu-type "nvidia-tesla-v100")
  (gpu-count 2))

unless​

Execute body when condition is false.

(unless (env? "SKIP_BASTION")
  (bastion (enabled true)))

cond​

Multiple condition branches.

(cond
  ((= env "production") "s-8vcpu-16gb")
  ((= env "staging")    "s-4vcpu-8gb")
  (true                 "s-2vcpu-4gb"))

default​

Return fallback if value is nil or empty.

(default (env "REGION") "nyc3")

or / and / not​

Boolean operations.

(or (env? "AWS_TOKEN") (env? "DO_TOKEN"))
(and (env? "PRODUCTION") (env? "ENABLE_HA"))
(not (env? "DISABLE_VPN"))

Comparison​

eq / =​

Equality comparison.

(eq (env "ENV") "production")
(= (env "COUNT") "3")

Comparison Operators​

!=, <, >, <=, >= - Compare values.

(!= (env "ENV") "development")
(< count 10)
(> workers 3)
(<= replicas 5)
(>= memory 8)

Arithmetic​

+ / - / * / /​

Basic arithmetic.

(+ 1 2 3)      ; 6
(- 10 3)       ; 7
(* 2 3 4)      ; 24
(/ 10 2)       ; 5

mod​

Modulo operation.

(mod 10 3)  ; 1

Encoding & Hashing​

base64-encode / base64-decode​

Base64 encoding/decoding.

(base64-encode "secret")
; "c2VjcmV0"

(base64-decode "c2VjcmV0")
; "secret"

sha256​

SHA-256 hash.

(sha256 "mypassword")
; "89e01536ac207279409d4de1e5253e01f4a1769e696db0d6062ca9b8f56767c8"

md5​

MD5-style hash (uses SHA-256 truncated).

(md5 "data")

UUID & Random​

uuid​

Generate UUID v4.

(uuid)
; "550e8400-e29b-41d4-a716-446655440000"

random-string​

Generate random alphanumeric string.

(random-string)      ; 16 chars default
(random-string 32)   ; custom length

Time & Date​

now​

Current UTC time in RFC3339 format.

(now)
; "2024-01-15T10:30:00Z"

timestamp​

Current Unix timestamp.

(timestamp)
; 1705315800

date​

Current date with custom format.

(date)                    ; "2024-01-15"
(date "2006/01/02")       ; "2024/01/15"
(date "Jan 02, 2006")     ; "Jan 15, 2024"

time​

Current time with custom format.

(time)                ; "10:30:00"
(time "15:04")        ; "10:30"

System Information​

hostname​

Get current hostname.

(hostname)
; "my-workstation"

user​

Get current username.

(user)
; "admin"

home​

Get user home directory.

(home)
; "/home/admin"

cwd​

Get current working directory.

(cwd)
; "/projects/my-cluster"

File Operations​

read-file​

Read file contents.

(read-file "~/.ssh/id_ed25519.pub")
(read-file "/etc/hostname")

file-exists?​

Check if file exists.

(if (file-exists? "~/.kube/config")
    (read-file "~/.kube/config")
    "")

dirname / basename​

Path manipulation.

(dirname "/path/to/file.txt")   ; "/path/to"
(basename "/path/to/file.txt")  ; "file.txt"

expand-path​

Expand path with ~ and make absolute.

(expand-path "~/configs")
; "/home/user/configs"

Shell Execution​

shell​

Execute shell command and return output.

(shell "whoami")
(shell "kubectl config current-context")
(shell "curl -s https://api.ipify.org")

Note: Dangerous commands are blocked for safety.

Variables​

let​

Define local variables in a scope.

(let ((region "nyc3")
      (size "s-4vcpu-8gb"))
  (node-pool
    (name "workers")
    (region region)
    (size size)))

var​

Get variable value.

(var "my-variable")

set​

Set variable value.

(set "cluster-name" "production")

List Operations​

list​

Create a list.

(list "a" "b" "c")

first / rest​

Get first element or remaining elements.

(first (list 1 2 3))  ; 1
(rest (list 1 2 3))   ; (2 3)

nth​

Get element at index.

(nth (list "a" "b" "c") 1)  ; "b"

len​

Get length of list or string.

(len (list 1 2 3))  ; 3
(len "hello")       ; 5

append​

Combine lists.

(append (list 1 2) (list 3 4))  ; (1 2 3 4)

range​

Generate number sequence.

(range 5)         ; (0 1 2 3 4)
(range 1 5)       ; (1 2 3 4)
(range 0 10 2)    ; (0 2 4 6 8)

Type Checking​

string? / number? / bool? / list? / nil? / empty?​

Check value types.

(string? "hello")     ; true
(number? 42)          ; true
(bool? true)          ; true
(list? (list 1 2))    ; true
(nil? nil)            ; true
(empty? "")           ; true
(empty? (list))       ; true

Type Conversion​

to-string / to-int / to-bool​

Convert between types.

(to-string 42)        ; "42"
(to-int "42")         ; 42
(to-bool "true")      ; true
(to-bool 1)           ; true

Regular Expressions​

match​

Extract matches from string.

(match "v([0-9]+)\\.([0-9]+)" "v1.28")
; ("v1.28" "1" "28")

match?​

Check if pattern matches.

(match? "^v[0-9]+" "v1.28")  ; true
(match? "^v[0-9]+" "1.28")   ; false

Practical Examples​

Dynamic Cluster Configuration​

(cluster
  (metadata
    (name (concat "k8s-" (env "ENV" "dev")))
    (environment (env "ENV" "development")))

  (providers
    (digitalocean
      (enabled true)
      (token (env "DIGITALOCEAN_TOKEN"))
      (region (env-or "DO_REGION" "nyc3"))))

  (node-pools
    (pool
      (name "masters")
      (count (if (= (env "ENV") "production") 3 1))
      (size (if (= (env "ENV") "production")
                "s-4vcpu-8gb"
                "s-2vcpu-4gb")))))

Reading SSH Keys from File​

(providers
  (digitalocean
    (ssh-keys
      (if (file-exists? "~/.ssh/id_ed25519.pub")
          (read-file "~/.ssh/id_ed25519.pub")
          (read-file "~/.ssh/id_rsa.pub")))))

Generating Unique Names​

(metadata
  (name (concat "cluster-" (substring (uuid) 0 8)))
  (created-at (now)))

Environment-Based Sizing​

(let ((env (env-or "CLUSTER_ENV" "development")))
  (node-pools
    (pool
      (name "workers")
      (count (cond
               ((= env "production") 10)
               ((= env "staging") 5)
               (true 2)))
      (size (cond
              ((= env "production") "s-8vcpu-16gb")
              ((= env "staging") "s-4vcpu-8gb")
              (true "s-2vcpu-4gb"))))))