Variables

Variables make templates flexible and reusable. They allow you to inject dynamic values into container specifications and volume definitions at runtime.

Variable Types

System Variables Automatically provided by knot. Include user information, space details, and server configuration.

User-Defined Variables Created by administrators in the web interface. Shared across templates for common configuration values.

Custom Variables Defined in templates. Users provide values when creating spaces for per-space customization.

Secret Providers Resolve secrets from an external manager such as Vault at template render time. Pro

Personal Secrets Users read their own 1Password secrets at runtime from the CLI and Scriptling, with a token on their profile. Pro

Variable Syntax

Variables use Go template syntax:

${{ .group.name }}

Examples:

${{ .user.username }} - Current user’s username
${{ .space.name }} - Space name
${{ .var.registry_url }} - User-defined variable
${{ .custom.branch }} - Custom variable
${{ secret "vault" "secret/data/prod/database" "password" }} - External secret provider

Common Use Cases

Dynamic Container Names

    
container_name: ${{ .user.username }}-${{ .space.name }}
hostname: ${{ .space.name }}

Creates unique container names like john-myproject.

User Home Directories

    
volumes:
  - home:/home/${{ .user.username }}

Mounts volumes to user-specific paths.

Environment Configuration

    
environment:
  - "TZ=${{ .user.timezone }}"
  - "USER=${{ .user.username }}"
  - "KNOT_SERVER=${{ .server.url }}"

Configures containers with user and server details.

Registry Authentication

    
auth {
  username = "${{ .var.registry_user }}"
  password = "${{ .var.registry_pass }}"
}

Uses user-defined variables for credentials.

Per-Space Configuration

    
environment:
  - "GIT_BRANCH=${{ .custom.branch }}"
  - "API_KEY=${{ .custom.api_key }}"

Allows users to customize each space.

External Secret Resolution

    
environment:
  - "DB_PASSWORD=${{ secret \"vault\" \"secret/data/prod/database\" \"password\" }}"

Fetches a secret from an external provider when the template is resolved.

What’s Next

System Variables: System variables are automatically provided by knot to reference space, template, user, and server details.
User Variables: User-defined variables are created in the web interface and shared across templates via the .var. prefix.
Custom Variables: Custom variables are defined in templates and set per-space using the .custom prefix when creating spaces.
Secret Providers: Secret providers fetch secrets from external managers like Vault and 1Password at template resolve time.
Personal Secrets: Read your own 1Password secrets inside your spaces, using a service account token stored on your profile.

Navigation