Reference

The one file that says what your application is: its containers and how each is built and tested, how it is deployed, and how its work is verified. Two shapes are covered here, an application and a Knative service. Specification v1.0.

TL;DR

You rarely write this file from scratch: a template comes with one, and the agent edits it when you say "add a second container" or "expose port 8080 at /api". Read this page when you want to know what a line means. A few dozen lines describe a whole application; the manifests under k8s/ are generated from them.

Thinkube GitOps explains what the file is for and what the platform generates from it. This page is the field-by-field lookup.

thinkube.yaml sits at the root of a repository. Thinkube Control reads it to build and deploy an application. Thinkube Tandem reads it to know where a repository’s tests live, how one of them runs, how the repository is made live when the platform does not do it, and where its documentation lands. Both read the file in place.

The example below is the file that deploys this documentation site:

# Copyright Alejandro Martínez Corriá and the Thinkube contributors
# SPDX-License-Identifier: Apache-2.0

apiVersion: thinkube.io/v1
kind: ThinkubeDeployment
metadata:
  # The application's version; the generated app starts at it.
  version: "0.1.4"

spec:
  deployment:
    type: app

  containers:
    - name: docs
      build: .
      port: 8080
      size: small
      health: /

  routes:
    - path: /
      to: docs

The machine-readable schema is thinkube-yaml-v1.0.schema.json.

Principles

  • A static descriptor. It has no conditionals and two substitutions only: {{ project_name }} and {{ domain_name }}.

  • Open standards. What you build is standard: a git repository with ordinary code, a Containerfile and OCI container images. Your work is portable and not tied to Thinkube. The platform services it uses (a PostgreSQL database, S3-compatible storage, OpenID Connect sign-in, an OCI image registry) have close, highly compatible equivalents at the main cloud providers.

  • Written without Kubernetes knowledge. You name containers, ports, routes and services. The platform derives the rest.

  • One to many containers. Always-on applications, scale-to-zero Knative services, and platform components with a fixed name.

  • Declared, never guessed. What only you can know about a repository is written here. Facts the platform can find out by running a command are not written here.

Schema

apiVersion: thinkube.io/v1
kind: ThinkubeDeployment
metadata:
  name: string              # Application name

spec:
  deployment:               # Deployment type and scaling (optional)
    type: string            # "app" (default), "knative", "component", "extension", or "none"
    name: string            # Component only: fixed deployment name
    replicas: number        # Initial replica count (default 1; 0 for gateway-managed components)
    gateway_managed: boolean  # An external controller creates the pods (default false)
    minScale: number        # Knative: minimum pods (default 0)
    maxScale: number        # Knative: maximum pods (default 5)
    containerConcurrency: number  # Knative: concurrent requests per pod (default 0 = unlimited)
    timeoutSeconds: number  # Knative: request timeout in seconds (default 300)

  extension:                # Extension only: how Thinkube Control shows it
    title: string           # The name in Control's navigation
    description: string     # One line about it (optional)
    icon: string            # A lucide icon name (optional)
    platform: string        # The platform MAJOR.MINOR it is built for, e.g. "0.1"
    depends: [string]       # Other extensions it needs (optional)
    ui:
      module: string        # An ES module that exports mount(element, host)
      css: string           # Its stylesheet, in the module's folder (optional)
    nav:                    # At least one entry in Control's navigation
      - label: string
        path: string        # A path of the extension, starting with /
        icon: string        # A lucide icon name (optional)

  llm_backend:              # This component is a backend of the LLM Gateway (optional)
    type: string            # The backend type models name in server_type, e.g. "vllm"
    display_name: string    # The name the platform shows, e.g. "vLLM"
    container: string       # The container that serves the models
    driver: string          # "per-model-pod" or "ollama"
    tier: string            # "performance" or "flexible"
    api_path: string        # The OpenAI API root (default "/v1")
    gpu_compute_capabilities:  # The GPUs the server runs on (optional; default any)
      - string              # A CUDA compute capability, e.g. "12.1"
    anthropic_messages: boolean  # The server answers the Anthropic Messages API (default false)

  containers:               # The containers the platform builds and runs
    - name: string          # Container identifier
      build: string         # Build context path
      port: number          # Container port (optional)
      size: string          # small / medium / large / xlarge (optional)
      buildSize: string     # Memory for the build: small / medium / large / xlarge (optional)
      health: string        # Health endpoint path (required when a port is exposed)
      startupSeconds: number  # GPU containers: time to answer health at start (default 600)
      nodeCache: string     # GPU containers: a folder on the node's local disk at this path (optional)
      schedule: string      # Cron expression for scheduled tasks (optional)
      mounts:               # Storage mounts (optional)
        - string            # "storage-name:/mount/path"
      gpu:                  # GPU requirements (optional)
        count: number
        memory: string
      capabilities:         # Special capabilities (optional)
        - string            # e.g. "large-uploads"
      publicEnv:            # Variables this container may show the browser (optional)
        - string            # A variable name, e.g. "APP_TITLE"
      test:                 # Tests, run before the build in CI (optional)
        enabled: boolean    # default false
        command: string     # The whole suite (required when enabled)
        image: string       # Test image override (optional)
        one: string         # How one test file runs; <file> is substituted (optional)
        size: string        # Memory and CPU for the tests: small / medium / large / xlarge (optional)
      migrations:           # Database migrations (optional)
        tool: string        # alembic, django, flyway, liquibase, prisma, sequelize, gorm, custom
        auto: boolean       # Run on startup (default true)

  parts:                    # Only for a repository with no containers: its trees, one toolchain each
    - name: string
      root: string          # Path relative to the repository root
      test:                 # As containers[].test
        enabled: boolean
        command: string
        image: string
        one: string

  deploy:                   # How this repository is made live when the platform does not do it
    run: string | list      # The command, or several in order (optional)
    in: string              # The directory it runs in, when it lives in another repository (optional)
    at: string              # Where the result can be seen (optional)

  verify:                   # For declarative work: how its own tool says the work holds
    still: string | list    # Commands that change nothing
    apply: string           # The command that does the work
    ask: string             # What reports whether anything is left to do
    settled: string         # What that report must say, e.g. "changed=0"

  docs:                     # Where documentation lands (optional)
    root: string            # Default "docs"

  routes:                   # HTTP routing (optional)
    - path: string
      to: string            # A container name

  services:                 # Platform services (optional)
    - string                # "database", "cache", "storage", "queue", "workflows", or "type:name"

  dependencies:             # Other deployed services this one needs (optional)
    - name: string
      type: string          # A template type or service class
      env: string           # The variable that receives the resolved URL

  env:                      # Variables you can set at deploy time (optional)
    - name: string
      description: string
      default: string

metadata

Field Type Description

metadata.name

string

The application name. Supports {{ project_name }}.

metadata.version

string

The application’s version, MAJOR.MINOR.PATCH. An application generated from a template starts at the template’s value; bump it when you release the application. Thinkube Control shows it on the application’s card.

The template an application was generated from has its own version: the newest vMAJOR.MINOR.PATCH tag of the template repository. A deploy uses that tag, and Copier records it in the application’s .copier-answers.yml.

spec.deployment

Optional. Defaults to type: app.

Field Type Description

type

string

app: an always-on Deployment, Service and HTTPRoute, named by you at deploy time. knative: a Knative Service that scales to zero. component: the same resources as app with a fixed name from deployment.name, for platform infrastructure that goes through the pipeline. extension: a part of Thinkube Control, deployed in Control’s namespace and shown inside Control; see spec.extension. none: the platform does not deploy this repository; see spec.deploy.

name

string

Component only, and required there. Lowercase alphanumeric with hyphens. It becomes the namespace, the service name, the domain prefix, the Thinkube Git repository name and the ArgoCD application name.

replicas

number

Initial replica count, default 1. 0 for components whose pods an external controller creates at runtime, such as the LLM Gateway placing inference pods per GPU. Forbidden for knative.

gateway_managed

boolean

Default false. An external controller creates this component’s pods at runtime. Its resting state is zero replicas, so the platform reports it as idle rather than scaled down, and keeps it listed as enabled.

minScale

number

Knative only. Default 0.

maxScale

number

Knative only. Default 5.

containerConcurrency

number

Knative only. Default 0, unlimited. 1 for CPU-heavy work, one request per pod.

timeoutSeconds

number

Knative only. Default 300. At most 900.

Knative portability

Knative services are meant to be portable to cloud serverless platforms. When type: knative, the schema enforces: a single container; no gpu, mounts, migrations, schedule or capabilities; no storage or workflows service; timeoutSeconds at most 900. Work that needs any of these uses app or component.

spec.extension

Required when deployment.type is extension, and only then. An extension is a part of Thinkube Control that is built and deployed on its own: a redeploy of it does not touch Control or the other extensions.

It runs in the thinkube-control namespace. Its Services are named <app>-<container>, so they do not meet Control’s own, and its objects carry the label app.kubernetes.io/name: <app>, by which a delete removes them. A few names are reserved for Control’s objects and cannot name an extension. An extension may declare the workflows service; see Workflows.

Control reads this block from the app’s thinkube.yaml on its Gitea main. It lists the extension in its navigation and draws its pages inside its own layout: it loads ui.module through /api/v1/x/<app>/ui/ and calls the module’s mount(element, host). The host gives the module Control’s address (basename, path(), listen(), navigate()) and request(), which sends a call through /api/v1/x/<app>/api/ to the extension’s /api/v1/ with the user’s session. An extension built for another platform version, or one whose depends are not all installed, is listed with the problem and its pages are not loaded.

The web app template renders this block when it is deployed with the variable extension: true.

Field Type Description

title

string

The name in Control’s navigation.

description

string

Optional. One line about the extension.

icon

string

Optional. A lucide icon name.

platform

string

The platform MAJOR.MINOR the extension is built for, for example "0.1".

depends

list of string

Optional. The names of other extensions it needs.

ui.module

string

A path of the extension’s site, starting with /: an ES module that exports mount(element, host) and returns the function that removes what it drew. Control serves the files of this module’s folder.

ui.css

string

Optional. Its stylesheet, in the same folder as the module.

nav

list

At least one entry: label, path (a path of the extension, starting with /) and an optional lucide icon.

spec.llm_backend

Optional. It makes the component a backend type of the LLM Gateway. The gateway reads it from the component’s service ConfigMap, so a new inference server is added with a template and no change to Thinkube Control. It requires deployment.type: component and deployment.gateway_managed: true.

Field Type Description

type

string

Required. Lowercase alphanumeric with hyphens. The name that models list in their server_type in the model catalog.

display_name

string

Required. The name Thinkube Control shows for this backend.

container

string

Required. The container that serves the models. It must declare a port. Its Deployment, <name>-<container>, rests at zero replicas; the gateway copies it for each model it loads, on the node the user chooses.

driver

string

Required. per-model-pod: one pod serves one model, and the gateway passes the model and its settings as environment variables (MODEL_ID, MAX_CONTEXT_LENGTH and others). ollama: one pod per node serves many models through the Ollama API.

tier

string

Required. performance or flexible. A request that asks for a tier with the X-LLM-Tier header is sent to a backend of that tier.

api_path

string

Default /v1, where the OpenAI API specification places its routes. The gateway probes <api_path>/models and the container’s health path.

gpu_compute_capabilities

list

Optional. The CUDA compute capabilities the server runs on, written major.minor, such as 12.1 for a DGX Spark. The gateway loads models only on nodes whose GPUs have one of them. Without it, the server runs on any GPU.

anthropic_messages

boolean

Default false. The server answers the Anthropic Messages API at <api_path>/messages. The gateway then forwards Anthropic requests to it with only the model name changed. Otherwise it translates them to OpenAI chat completions.

spec.containers

At least one container, unless deployment.type is none.

Field Type Description

name

string

Unique identifier, used in routes. For example backend, frontend, worker.

build

string

Build context relative to the repository root: ., ./backend.

port

number

The port the container listens on, 1 to 65535. Optional for workers and jobs.

size

string

small 256Mi and 100m CPU, medium 512Mi and 500m, large 1Gi and 1000m, xlarge 80Gi and 4000m for unified-memory systems. Default small.

buildSize

string

The memory the container’s build pod gets: small 4Gi, medium 8Gi, large 16Gi, xlarge 32Gi. Default small. Separate from size, because a build can need far more than the container runs in: a frontend served in 512Mi can need 8Gi to bundle. While training mode is on, builds also run on its node, one at a time; an xlarge build is refused there, with an error, when no other node of its architecture can take it.

health

string

Health endpoint path, required when a port is exposed. Standard value /health. See the health endpoints specification.

startupSeconds

number

GPU containers with a health path only. The seconds the container may take to answer its health path when it starts, before it is restarted. Default 600. An inference server that loads a large model before it opens its port needs more.

nodeCache

string

GPU containers only. An absolute path where the container gets a folder on the local disk of the node it runs on, kept across restarts and shared by the component’s pods on that node. Every user in the container may write to it. Its path is also in NODE_CACHE_DIR. For local copies of large files the server reads at random while it serves, such as a model package on Thinkube Storage. The folder is not backed up and is not cleaned by the platform.

schedule

string

A cron expression. The container runs as a job and has no persistent pods.

mounts

list

storage-name:/mount/path. The storage must be declared under services.

gpu

object

count and memory are both required. The platform allocates that many GPUs with at least that memory each, preferring the smallest GPU that fits.

capabilities

list

large-uploads configures the gateway for uploads up to 1GB.

publicEnv

list

Names of variables this container may show the browser. See below.

test

object

See below.

migrations

object

tool is one of alembic, django, flyway, liquibase, prisma, sequelize, gorm, custom. auto, default true, runs them on startup.

containers[].test

Tests run in CI before the container is built, in the named image. The build and the deployment run only when the tests pass. Results are reported to Thinkube Control.

Field Type Description

enabled

boolean

Default false.

command

string

Runs the whole suite. Required when enabled.

image

string

The image the tests run in. Optional; the platform chooses a base image for the container’s language.

one

string

Runs a single test file. <file> is replaced by the file’s path relative to the container’s build directory. Optional. Thinkube Tandem uses it to run one test file at a time while it builds a change. When one is absent, Tandem works out the command from the repository’s own tests and keeps the command it has shown to work.

size

string

The memory and CPU the test pod gets: small 1Gi and 1 CPU, medium 4Gi and 2 CPUs, large 8Gi and 4 CPUs, xlarge 16Gi and 8 CPUs. Default small. A suite that loads the whole application and runs thousands of tests needs more than one that checks a single service.

The tests run on a copy of the container’s build directory. The pod also has:

Variable What it holds

TEST_DATABASE_NAME

The database the tests own, test_<app>, created by the deploy when tests are enabled.

ADMIN_USERNAME, ADMIN_PASSWORD

The credentials for the platform’s PostgreSQL.

SOURCE_ROOT

The whole checkout, to read only. A test that checks the repository itself, such as its documentation or another part, reads it here.

Keep the test environment in one place. The application templates give each container a run_tests.sh that runs the whole suite without arguments and one file with a file argument, so command is ./run_tests.sh and one is ./run_tests.sh <file>, and the settings a test needs are set in the script, never repeated in this file.

containers[].publicEnv

Names of variables this container may show the browser.

A container reads its variables from its environment. A browser application cannot: it is a bundle built before the deployment exists, and by the time it runs it is a file served by a web server. publicEnv lets a variable reach the page. The platform sets PUBLIC_ENV_VARS in the container to the names listed here, and the image’s entrypoint writes those variables, and only those, where the page can read them.

containers:
  - name: frontend
    build: ./frontend
    port: 80
    health: /health
    publicEnv:
      - APP_TITLE
      - API_BASE_URL

Any variable the container has can be named: one the platform sets such as APP_TITLE, one declared in spec.env, one wired from dependencies, or a parameter answered at deploy time. The list holds names, never values. Values reach the container from the deployment, so a template carries the list and never the answers.

The list is an allow-list, and an absent list means nothing is published. This matters: every container receives the whole environment, including POSTGRES_PASSWORD, KEYCLOAK_CLIENT_SECRET and ADMIN_PASSWORD. A container that wrote its environment to the page would serve those to every visitor. Name a variable here only when it is safe for anyone who opens the application to read it, and treat a secret in this list as a disclosed secret.

spec.parts

Only for a repository with deployment.type: none. Each part is a tree with its own toolchain: where its files are, and how its tests run there. A repository with containers does not declare parts; its containers are its parts.

Field Type Description

name

string

The part’s identifier.

root

string

Path relative to the repository root.

test

object

As containers[].test.

spec.deploy

How the repository is made live when the platform does not do it. An application usually omits this block: the platform deploys it from containers. It may still carry at on its own, to say where the result can be seen.

Field Type Description

run

string or list

The command that makes it live, or several to run in order, stopping at the first that fails. Optional: no run means the merge itself made it live.

in

string

The directory to run it in, when the command lives in another repository. Optional.

at

string

Where the result can be seen, a URL. Optional. Thinkube Tandem opens it to look at what was delivered.

spec.verify

For repositories whose work is declarative, such as playbooks. For playbooks, the check is that a second run changes nothing.

Field Type Description

still

string or list

Commands that change nothing: lint, syntax check, a dry run with a diff. One or several. Run before anything is merged.

apply

string

The command that does the work. It is the deployment, and runs only after a person approves it.

ask

string

The command that reports whether anything is left to do, run after apply.

settled

string

What that report must say for the work to be settled, for example changed=0. A second run that still changes something is a defect.

spec.docs

Where documentation lands. Every delivery documents what it changed. When the work changes no documentation page, Thinkube Tandem adds one to what the change must deliver.

Field Type Description

root

string

Default docs. Markdown pages under this directory. When the directory holds an antora.yml, the site is Antora and pages land as .adoc under its ROOT module, listed in its nav.adoc.

spec.routes

HTTP routes, implemented as Gateway API HTTPRoute resources with the platform’s wildcard certificates.

Field Type Description

path

string

A path prefix: /, /api.

to

string

The container that serves it.

spec.services

Platform services the application needs. Each declared service injects variables into every container.

Service Variables injected into every container

database

DATABASE_URL

cache

CACHE_URL

storage

STORAGE_<NAME>_URL

queue

QUEUE_URL

workflows

WORKFLOWS_NAMESPACE, WORKFLOWS_SERVER_URL, WORKFLOWS_SERVICE_ACCOUNT, WORKFLOWS_UI_URL, WORKFLOWS_ARTIFACT_REPOSITORY, and one CONTAINER_IMAGE_<NAME> for each container in this file

database, cache, storage and queue take an optional type:name suffix for a named instance, such as storage:uploads. workflows does not: an application has one.

workflows is refused for deployment.type: knative. See Knative portability.

Workflows

workflows gives the application its own access to Argo Workflows, in its own namespace. The platform creates a ServiceAccount <app>-workflows that every pod runs as, a Role allowing it to manage workflows in that namespace, and a default artifact repository in Thinkube Storage under the prefix <app>/. Steps run in the application’s own images, named by CONTAINER_IMAGE_<NAME>, and count against the namespace’s ResourceQuota. See Run a pipeline from your app.

WORKFLOWS_ARTIFACT_REPOSITORY names the ConfigMap of that artifact repository. A workflow that sets spec.artifactRepositoryRef.configMap to it runs the same in an application and in an extension.

An extension (deployment.type: extension) submits its workflows into Thinkube Control’s namespace, thinkube-control, which several extensions share. Its objects carry its name: the ServiceAccount, Role and RoleBinding <app>-workflows, the ConfigMap <app>-artifact-repositories and the Secret <app>-artifacts-s3. Its Role creates, reads, lists and deletes workflows, reports step results, and reads pods and their logs; it does not reach workflow templates or cron workflows. Its artifacts go to the bucket argo-artifacts under the prefix <app>/, as an application’s do. That namespace has no default artifact repository, so each workflow of an extension names WORKFLOWS_ARTIFACT_REPOSITORY in spec.artifactRepositoryRef.configMap; one that names none has no artifact repository. Workflow pods count against the namespace’s ResourceQuota and take its LimitRange defaults when a step sets no resources. Nothing keeps them off GPU nodes; a step that needs no GPU sets a nodeSelector or an affinity itself.

spec.dependencies

Other deployed services this application needs. At deploy time Thinkube Control resolves each to the running service’s cluster URL and injects it as the named variable. If the dependency is not deployed, the deployment fails and says which one.

Field Type Description

name

string

The name shown in the interface and in errors.

type

string

The service to look for, by name. Common types: llm-proxy (the LLM Gateway, OpenAI API), texplitter, text-embeddings, ollama, seaweedfs.

env

string

The variable that receives the URL: LLM_GATEWAY_URL, TEXPLITTER_URL.

A type is matched against the services running on the cluster, in this order:

  1. a Knative service whose name or namespace contains the type; its address is used;

  2. a Service whose name and namespace both contain the type;

  3. a Service whose name contains the type.

The URL is http://<service>.<namespace>.svc.cluster.local:<first port>. A Knative service that matches but is not ready yet, or a Service that matches but exposes no port, fails the deployment with a message naming it.

For example, an application that calls models through the LLM Gateway declares:

dependencies:
  - name: llm-gateway
    type: llm-proxy
    env: LLM_GATEWAY_URL

spec.env

Variables you can set when you deploy. Thinkube Control shows them with their descriptions; a variable with no default is required. They are injected into every container. A variable wired from dependencies wins over an entry here with the same name.

Field Type Description

name

string

Uppercase with underscores.

description

string

Shown in the deployment interface.

default

string

Optional.

A variable declared here reaches the containers. To let a browser application read one, name it in that container’s publicEnv.

Examples

A minimal application

apiVersion: thinkube.io/v1
kind: ThinkubeDeployment
metadata:
  name: "{{ project_name }}"

spec:
  containers:
    - name: app
      build: .
      port: 3000
      health: /health

A web application with a database and tests

apiVersion: thinkube.io/v1
kind: ThinkubeDeployment
metadata:
  name: "{{ project_name }}"

spec:
  containers:
    - name: backend
      build: ./backend
      port: 8000
      health: /health
      test:
        enabled: true
        command: "pytest --cov=app"
        one: "pytest <file>"
      migrations:
        tool: alembic
        auto: true

    - name: frontend
      build: ./frontend
      port: 80
      health: /health
      publicEnv:
        - APP_TITLE
      test:
        enabled: true
        command: "npx vitest run"
        one: "npx vitest run <file>"

  routes:
    - path: /api
      to: backend
    - path: /
      to: frontend

  services:
    - database

A Knative processing service

apiVersion: thinkube.io/v1
kind: ThinkubeDeployment
metadata:
  name: "{{ project_name }}"

spec:
  deployment:
    type: knative
    minScale: 0
    maxScale: 3
    containerConcurrency: 1
    timeoutSeconds: 600

  containers:
    - name: aligner
      build: .
      port: 8080
      size: medium
      health: /health

  dependencies:
    - name: texplitter
      type: texplitter
      env: TEXPLITTER_URL
    - name: ollama
      type: ollama
      env: OLLAMA_URL

  env:
    - name: OLLAMA_MODEL
      description: "LLM model for alignment validation"
      default: "qwen3.5-ner:notk"

  routes:
    - path: /
      to: aligner

A web application with a pipeline

The verification application of Run a pipeline from your app: the web app template with workflows added to its services.

apiVersion: thinkube.io/v1
kind: ThinkubeDeployment

spec:
  deployment:
    type: app

  containers:
    - name: backend
      build: ./backend
      port: 8000
      size: medium
      health: /health
      test:
        enabled: true
        image: "python-base:3.12-slim"
        command: "./run_tests.sh"
        one: "./run_tests.sh <file>"
      migrations:
        tool: alembic
        auto: true

    - name: frontend
      build: ./frontend
      port: 80
      size: small
      health: /health
      publicEnv:
        - APP_TITLE
      test:
        enabled: true
        # node-base carries git, which npm needs to install thinkube-style
        image: "node-base:22-alpine"
        command: "./run_tests.sh"
        one: "./run_tests.sh <file>"

  routes:
    - path: /api
      to: backend
    - path: /
      to: frontend

  services:
    - database
    - workflows

What belongs elsewhere

The file describes the application. Container-specific configuration belongs in the Containerfile, and orchestration to Thinkube Control, so the file stays a static descriptor with no conditional logic, raw Kubernetes resources, deployment strategies or command overrides.

Version

Specification v1.0.

Scope

This page covers applications and Knative services. The same file also describes the platform’s own components and repositories the platform does not deploy; those uses belong to platform development.