Blueprint Syntax Reference

This page documents the complete YAML schema for Teabar blueprints.

Full Schema

apiVersion: teabar.dev/v1      # Required: API version
kind: Blueprint                 # Required: Resource type

metadata:
  name: string                  # Required: Blueprint identifier (lowercase, hyphens)
  description: string           # Optional: Human-readable description
  version: string               # Optional: Blueprint version (semver)
  labels:                       # Optional: Key-value labels
    key: value
  annotations:                  # Optional: Non-identifying metadata
    key: value

spec:
  # Environment Lifecycle
  ttl: duration                 # Optional: Time-to-live (e.g., "8h", "2d")
  schedule:                     # Optional: Auto-start/stop schedule
    start: cron                 # Cron expression for start time
    stop: cron                  # Cron expression for stop time
    timezone: string            # Timezone (default: UTC)

  # Infrastructure
  provider: string              # Required: Cloud provider (hetzner, aws, azure)
  region: string                # Optional: Provider region
  network:                      # Optional: Network configuration
    cidr: string                # Network CIDR (default: 10.0.0.0/16)
    public: boolean             # Enable public IPs (default: true)

  # Components
  components:                   # Required: List of infrastructure components
    - name: string              # Required: Component name
      type: string              # Required: Component type
      # ... component-specific options

  # Participants
  participants:                 # Optional: Participant configuration
    count: integer              # Number of participants
    isolation: string           # Isolation mode (namespace, cluster, vm)
    resources:                  # Per-participant resources
      cpu: string
      memory: string
      storage: string

  # Activity Tracking
  tracking:                     # Optional: Activity tracking config
    enabled: boolean
    events: []string            # Event types to track
    retention: duration         # How long to keep data

  # Hooks
  hooks:                        # Optional: Lifecycle hooks
    preCreate: string           # Script to run before creation
    postCreate: string          # Script to run after creation
    preDestroy: string          # Script to run before destruction

Metadata

metadata.name

Required. Unique identifier for the blueprint. Must be lowercase letters, numbers, and hyphens.

metadata:
  name: gitlab-cicd-training

metadata.labels

Key-value pairs for organizing blueprints:

metadata:
  labels:
    team: devops
    difficulty: intermediate
    duration: half-day

Spec Fields

spec.ttl

Time-to-live for environments created from this blueprint. Supports:

• 30m - 30 minutes
• 4h - 4 hours
• 2d - 2 days

spec:
  ttl: 8h # Environment auto-destroys after 8 hours

spec.provider

Cloud provider for infrastructure:

spec:
  provider: hetzner
  region: eu-central

spec.components

List of infrastructure components. See Components for all available types.

spec:
  components:
    - name: gitlab
      type: gitlab
      version: '16.8'
      resources:
        cpu: 4
        memory: 8Gi

    - name: cluster
      type: kubernetes
      version: '1.29'
      nodes:
        control: 1
        worker: 3

Kubernetes Version Pinning

Teabar supports the latest 3 minor versions of Kubernetes. Specify versions explicitly for production stability.

Version Syntax

spec:
  components:
    - name: cluster
      type: kubernetes
      
      # Exact version (recommended for production)
      version: '1.29'           # Uses latest patch of 1.29
      
      # Version constraint
      version: '>=1.28,<1.31'   # Resolves to highest matching
      
      # Latest (not recommended for production)
      version: 'latest'         # Current stable version

Supported Versions

Upgrade Policy

spec:
  components:
    - name: cluster
      type: kubernetes
      version: '1.29'
      
      # Upgrade settings
      upgrade:
        automatic: false        # Never auto-upgrade (default)
        # OR
        automatic: true
        window: 'sunday 02:00-06:00 UTC'
        notifyBefore: 7d

Version Validation

Check version compatibility before deploying:

# Check K8s versions used by blueprint
teactl blueprint validate my-blueprint.yaml

# List supported versions
teactl k8s versions

spec.participants

Configure participant workspaces:

spec:
  participants:
    count: 20 # Number of participants
    isolation: namespace # namespace | cluster | vm
    resources:
      cpu: 1
      memory: 2Gi
      storage: 10Gi
    access:
      ssh: true # Enable SSH access
      web: true # Enable web terminal

Isolation Modes

spec.tracking

Enable activity tracking for participants:

spec:
  tracking:
    enabled: true
    events:
      - git-push
      - git-pull
      - pipeline-run
      - kubectl-command
      - shell-command
    retention: 30d

spec.hooks

Run scripts at lifecycle events:

spec:
  hooks:
    postCreate: |
      #!/bin/bash
      # Clone exercise repository for all participants
      for ns in $(kubectl get ns -l teabar.dev/participant -o name); do
        kubectl -n $ns create secret generic exercises 
          --from-literal=repo=https://example.com/exercises
      done

Variables

Use variables for dynamic configuration:

spec:
  variables:
    participant_count:
      type: integer
      default: 10
      description: Number of participants

  participants:
    count: ${{ variables.participant_count }}

See Variables for more details.

Validation

Validate your blueprint before deploying:

teactl blueprint validate my-blueprint.yaml

Common validation errors:

• Missing required field - Ensure apiVersion, kind, metadata.name, and spec.provider are set
• Invalid component type - Check Components for valid types
• Resource limits exceeded - Your plan may limit certain resources