Blueprint Catalog

The Teabar catalog is a registry of blueprints that you can browse, use, and publish. It includes official Teabar blueprints, community contributions, and your organization’s private blueprints.

Catalog Structure

┌─────────────────────────────────────────────────────────────────────────┐
│                          Blueprint Catalog                               │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                    Official (teabar/*)                           │   │
│  │  Maintained by Teabar team, tested, production-ready            │   │
│  │  • teabar/kubernetes-basic                                      │   │
│  │  • teabar/gitlab-cicd                                           │   │
│  │  • teabar/monitoring-stack                                      │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                    Community (org-name/*)                        │   │
│  │  Published by Pro organizations, automated validation           │   │
│  │  • acme/custom-workshop                                         │   │
│  │  • techcorp/dev-environment                                     │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                    Private (your-org/*)                          │   │
│  │  Your organization's blueprints, visible only to members        │   │
│  │  • your-org/internal-training                                   │   │
│  │  • your-org/company-standards                                   │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

Browsing the Catalog

CLI Search

# Search by keyword
teactl catalog search kubernetes

# Search with filters
teactl catalog search gitlab --tag cicd --tag education

# Search official blueprints only
teactl catalog search --source official

# Search community blueprints
teactl catalog search --source community

List Blueprints

# List all available blueprints
teactl catalog list

# List with details
teactl catalog list --output wide

# Filter by tag
teactl catalog list --tag kubernetes

# List specific namespace
teactl catalog list --namespace teabar

View Blueprint Details

# Get detailed information
teactl catalog info teabar/kubernetes-basic

# Output:
# Blueprint: teabar/kubernetes-basic
# Version: 1.5.2 (latest)
# 
# Description:
#   Basic Kubernetes cluster for learning and development.
#   Includes a single control plane and configurable workers.
#
# Tags: kubernetes, training, beginner
# Author: Teabar Team
# Downloads: 12,453
# Rating: 4.8/5 (234 reviews)
#
# Variables:
#   worker_count    integer  Number of worker nodes (default: 2)
#   k8s_version     string   Kubernetes version (default: "1.28")
#   enable_metrics  boolean  Enable metrics server (default: true)
#
# Resources:
#   • 1 Kubernetes cluster (Talos)
#   • Metrics server (optional)
#   • Nginx ingress controller
#
# Available Versions:
#   1.5.2 (latest)  2024-01-15
#   1.5.1           2024-01-10
#   1.5.0           2024-01-05
#   1.4.x           (3 versions)

TUI Browser

Launch the interactive catalog browser:

# Open TUI catalog browser
teactl catalog browse

# Start with search query
teactl catalog browse --query gitlab

The TUI provides:

Searchable list with tag filters
Preview pane with description and variables
Version selector
One-key actions (use, install, view YAML)

Using Catalog Blueprints

Create Environment Directly

# Create environment from catalog blueprint
teactl env create --blueprint teabar/kubernetes-basic --name my-cluster

# With variables
teactl env create --blueprint teabar/gitlab-cicd 
  --name workshop 
  --var participant_count=20 
  --var gitlab_version="16.8"

Install to Project

Copy a catalog blueprint to your project for customization:

# Install blueprint to your project
teactl catalog install teabar/kubernetes-basic

# Install specific version
teactl catalog install teabar/kubernetes-basic --version 1.5.0

# Install with different name
teactl catalog install teabar/kubernetes-basic --as my-k8s-base

After installation, the blueprint appears in your project and can be customized:

# List project blueprints
teactl blueprint list

# Edit the installed blueprint
teactl blueprint edit my-k8s-base

Extend Catalog Blueprints

Use catalog blueprints as a base:

apiVersion: teabar.dev/v1
kind: Blueprint
metadata:
  name: my-workshop
  version: 1.0.0

spec:
  extends:
    - name: teabar/kubernetes-basic
      version: "1.x"
  
  # Add your customizations
  resources:
    helm:
      - name: my-app
        chart: my-repo/my-app

Official Blueprints

Maintained by the Teabar team with guaranteed quality:

Kubernetes

Blueprint	Description
`teabar/kubernetes-basic`	Single cluster, basic training
`teabar/kubernetes-ha`	HA cluster with 3 control planes
`teabar/kubernetes-multi`	Multiple clusters for federation
`teabar/kind-local`	Kind cluster for local development

CI/CD

Blueprint	Description
`teabar/gitlab-cicd`	GitLab CE with runners and registry
`teabar/github-actions`	Self-hosted GitHub runners
`teabar/jenkins`	Jenkins with agent pods
`teabar/argocd`	ArgoCD for GitOps workflows

Monitoring & Observability

Blueprint	Description
`teabar/monitoring-stack`	Prometheus + Grafana + Alertmanager
`teabar/logging-stack`	Loki + Promtail + Grafana
`teabar/tracing-stack`	Jaeger for distributed tracing

Security

Blueprint	Description
`teabar/security-training`	Falco, Trivy, OPA Gatekeeper
`teabar/vault`	HashiCorp Vault deployment

Development

Blueprint	Description
`teabar/dev-environment`	Full development environment
`teabar/database-playground`	PostgreSQL, MySQL, MongoDB, Redis

Tip

Official blueprints are prefixed with teabar/ and are always free to use. Browse the full catalog at teabar.dev/catalog.

Publishing Blueprints

Private Blueprints (Organization)

Push blueprints to your organization:

# Push blueprint to organization
teactl blueprint push -f my-blueprint.yaml

# Push with specific version
teactl blueprint push -f my-blueprint.yaml --version 1.0.0

# Push to specific organization (if member of multiple)
teactl blueprint push -f my-blueprint.yaml --org acme

Private blueprints are visible only to organization members.

Public Blueprints (Pro Feature)

Publish to the public catalog:

# Publish as public blueprint
teactl blueprint publish -f my-blueprint.yaml 
  --public 
  --description "Complete CI/CD training environment"

# Blueprint will be available as: your-org/blueprint-name

Note

Public publishing requires a Pro subscription and passes automated validation checks.

Publishing Requirements

Public blueprints must meet these criteria:

Requirement	Description
Syntax valid	No YAML errors, valid schema
Variables documented	All variables have descriptions
No hardcoded secrets	No API keys, passwords, tokens
Resources valid	All referenced resources exist
Tested	Successfully creates an environment

# Validate before publishing
teactl blueprint validate -f my-blueprint.yaml --strict

# Run publication checks
teactl blueprint check -f my-blueprint.yaml --for-publication

Managing Published Blueprints

Update Published Blueprint

# Push new version
teactl blueprint push -f my-blueprint.yaml --version 1.1.0

# Mark version as latest
teactl blueprint tag acme/my-blueprint:1.1.0 --latest

Deprecate Blueprint

# Deprecate a version (still usable, shows warning)
teactl blueprint deprecate acme/my-blueprint:1.0.0 
  --message "Use 2.x instead"

# Deprecate entire blueprint
teactl blueprint deprecate acme/my-blueprint 
  --message "Replaced by acme/my-new-blueprint"

Delete Blueprint

# Delete specific version (if no environments use it)
teactl blueprint delete acme/my-blueprint:1.0.0

# Delete entire blueprint (requires confirmation)
teactl blueprint delete acme/my-blueprint --all-versions

Warning

You cannot delete blueprints or versions that have active environments. Terminate all environments first.

Version Management

Semantic Versioning

Blueprints use semantic versioning (SemVer):

MAJOR.MINOR.PATCH

1.0.0 → 1.0.1 (patch: bug fixes)
1.0.0 → 1.1.0 (minor: new features, backward compatible)
1.0.0 → 2.0.0 (major: breaking changes)

Version Tags

# List all versions
teactl blueprint versions teabar/kubernetes-basic

# Tag a version
teactl blueprint tag acme/my-blueprint:1.5.0 --latest
teactl blueprint tag acme/my-blueprint:1.5.0 --stable
teactl blueprint tag acme/my-blueprint:2.0.0-beta.1 --beta

Using Version Constraints

When referencing blueprints:

extends:
  # Exact version (most stable)
  - name: teabar/base
    version: "1.5.2"
  
  # Any 1.x version (allows minor updates)
  - name: teabar/monitoring
    version: "1.x"
  
  # Any 1.5.x version (allows patches)
  - name: teabar/security
    version: "1.5.x"
  
  # Latest (not recommended for production)
  - name: teabar/dev-tools
    version: "latest"

Catalog API

Query the catalog programmatically:

Search

# JSON output for scripting
teactl catalog search kubernetes --output json

# Filter fields
teactl catalog search kubernetes --output json 
  --fields name,version,description

Get Blueprint YAML

# Download blueprint definition
teactl catalog get teabar/kubernetes-basic --output yaml > k8s-basic.yaml

# Get specific version
teactl catalog get teabar/kubernetes-basic:1.5.0 --output yaml

Check for Updates

# Check if newer versions exist
teactl catalog check-updates

# Output:
# Blueprint                    Current  Latest  Update Available
# teabar/kubernetes-basic      1.4.0    1.5.2   Yes (minor)
# teabar/gitlab-cicd           2.1.0    2.1.0   No
# acme/internal-training       1.0.0    1.2.0   Yes (minor)

Caching

The catalog is cached locally for performance:

# View cache status
teactl catalog cache status

# Clear cache
teactl catalog cache clear

# Update cache
teactl catalog cache update

Cache settings in config:

# ~/.teactl/config.yaml
catalog:
  cache_ttl: 1h        # How long to cache catalog
  auto_update: true    # Update cache automatically

Ratings and Reviews

View Ratings

teactl catalog info teabar/kubernetes-basic --reviews

# Output:
# Rating: 4.8/5 (234 reviews)
#
# Recent Reviews:
# ★★★★★ "Perfect for K8s training" - [email protected] (2024-01-10)
# ★★★★☆ "Good but needs better docs" - [email protected] (2024-01-08)

Submit Review

# Rate a blueprint you've used
teactl catalog review teabar/kubernetes-basic 
  --rating 5 
  --comment "Excellent for workshops!"

Best Practices

Choosing Blueprints

Start with official - teabar/* blueprints are tested and maintained
Check ratings - Higher-rated blueprints are more reliable
Review variables - Ensure it’s configurable for your needs
Check versions - Use actively maintained blueprints
Test first - Create a test environment before production use

Publishing Blueprints

Document thoroughly - Add descriptions to all variables
Use semantic versioning - Follow SemVer for updates
Test before publishing - Validate and create test environments
Maintain actively - Update for new Kubernetes versions, etc.
Respond to issues - Help users who have problems

Next Steps

Blueprint Syntax - Full schema reference
Blueprint Composition - Extend catalog blueprints
Blueprint Examples - Real-world configurations