Blueprints

Blueprints are the core abstraction in Teabar. They are declarative YAML definitions that describe everything needed to provision a complete environment - from infrastructure resources to applications to access controls.

What is a Blueprint?

A blueprint is a template that defines:

• Resources: What infrastructure and applications to deploy
• Variables: Configurable parameters with defaults and constraints
• Composition: How to extend or combine other blueprints
• Lifecycle: How the environment should behave (TTL, sleep mode, etc.)

Think of blueprints like Docker Compose files, but for entire environments that can span multiple Kubernetes clusters, VMs, cloud services, and more.

Basic Example

Here’s a simple blueprint that creates a development environment:

apiVersion: teabar.dev/v1
kind: Blueprint
metadata:
  name: dev-environment
  description: Basic development environment with database

variables:
  - name: app_name
    type: string
    default: myapp
  - name: db_size
    type: string
    default: small
    enum: [small, medium, large]

resources:
  - name: app
    type: kubernetes
    spec:
      manifests:
        - apiVersion: apps/v1
          kind: Deployment
          metadata:
            name: "{{ .Variables.app_name }}"
          spec:
            replicas: 1
            template:
              spec:
                containers:
                  - name: app
                    image: "{{ .Variables.app_name }}:latest"

  - name: database
    type: helm
    spec:
      chart: postgresql
      repo: https://charts.bitnami.com/bitnami
      values:
        primary:
          resources:
            requests:
              memory: "{{ if eq .Variables.db_size "small" }}256Mi{{ else }}1Gi{{ end }}"

Key Capabilities

Variables with Rich Schema

Variables aren’t just simple key-value pairs. They support:

• Types: string, integer, number, boolean, array, object
• Constraints: min/max, patterns, enums
• UI hints: Labels, descriptions, grouping for wizard rendering
• Defaults: Sensible defaults for optional configuration

variables:
  - name: participant_count
    type: integer
    default: 10
    constraints:
      min: 1
      max: 50
    ui:
      label: "Number of Participants"
      description: "How many participant workspaces to create"
      group: "Workshop Settings"

Go Templating

Blueprints use Go templates for dynamic configuration:

resources:
  {{- range $i := until .Variables.participant_count }}
  - name: participant-{{ $i }}
    type: kubernetes
    spec:
      namespace: participant-{{ $i }}
  {{- end }}

Available template functions include:

• All Sprig functions
• until, untilStep for loops
• toYaml, toJson for serialization
• Custom Teabar functions for secrets, lookups, etc.

Layered Composition

Blueprints can extend and combine other blueprints:

apiVersion: teabar.dev/v1
kind: Blueprint
metadata:
  name: cicd-advanced

extends:
  - blueprint: teabar/cicd-basics
    variables:
      gitlab_version: "16.0"

layers:
  - blueprint: teabar/monitoring-stack
  - blueprint: teabar/security-tools

This enables:

• Reusability: Build on proven base blueprints
• Customization: Override variables and resources
• Modularity: Compose environments from smaller pieces

Resource Types

Blueprints support multiple resource types:

Secret Management

Blueprints can generate secrets or pull from external sources:

secrets:
  # Auto-generated password
  - name: db_password
    generate:
      type: password
      length: 32

  # From external secret manager
  - name: api_key
    external:
      provider: vault
      path: secret/data/myapp
      key: api_key

Blueprint Lifecycle

Creation

# Create from local file
teactl blueprint create -f my-blueprint.yaml

# Create from catalog
teactl blueprint install teabar/cicd-workshop

Validation

# Validate syntax and references
teactl blueprint validate my-blueprint.yaml

# Render with variables to preview output
teactl blueprint render my-blueprint.yaml --var participant_count=5

Versioning

Blueprints are versioned automatically:

# List versions
teactl blueprint versions my-blueprint

# Use specific version
teactl env create --blueprint my-blueprint:v3

Blueprint Catalog

Teabar provides a catalog of pre-built blueprints:

Official Blueprints (teabar/*)

Organization Blueprints

Pro tier organizations can publish blueprints to the catalog:

# Publish to catalog
teactl blueprint publish my-blueprint --public

# Search catalog
teactl catalog search "kubernetes training"

Best Practices

1. Use Meaningful Defaults

Always provide sensible defaults so users can deploy without configuration:

variables:
  - name: replicas
    type: integer
    default: 2  # Works out of the box

2. Document Variables

Use UI hints to make blueprints self-documenting:

variables:
  - name: storage_class
    type: string
    default: standard
    ui:
      label: "Storage Class"
      description: "Kubernetes storage class for persistent volumes"
      group: "Advanced"

3. Use Composition

Don’t duplicate - extend existing blueprints:

extends:
  - blueprint: teabar/base-workshop

4. Validate Before Deploy

Always validate blueprints before using them:

teactl blueprint validate my-blueprint.yaml

5. Version Your Blueprints

Use Git for blueprint source control and tag releases.

Next Steps