Examples

Learn how to use Conductor Framework through practical examples.

Introduction

The examples demonstrate real-world usage of Conductor Framework for managing Kubernetes applications. They show how to structure manifests, configure parameters, and deploy services.

Prerequisites

  • Go 1.25.4+ (or latest stable version)
  • Docker (or compatible container runtime)
  • Kubernetes cluster (local or remote)
  • kubectl configured to access your cluster

Guestbook Conductor Example

The Guestbook Conductor is a working example that demonstrates how to use the conductor-framework to manage a multi-service Kubernetes application. The Guestbook application is a classic Kubernetes example consisting of:

  • Frontend: Web server (PHP) serving the guestbook UI
  • Redis Master: Primary Redis instance for data storage
  • Redis Slave: Redis replica for read scaling

This conductor manages all three services using the conductor-framework's manifest reconciliation capabilities.

What It Demonstrates

  • Manifest reconciliation for multiple services
  • Template-based manifest generation with parameters
  • CRD-based parameter management
  • Service deployment and monitoring
  • Event tracking and error handling

Project Structure

guestbook-conductor/
├── main.go              # Conductor entry point
├── Dockerfile           # Container build
├── README.md            # Documentation
├── go.mod               # Go module file
├── manifests/           # Kubernetes manifests
│   ├── frontend/
│   │   ├── deployment.yaml
│   │   └── service.yaml
│   ├── redis-master/
│   │   ├── deployment.yaml
│   │   └── service.yaml
│   └── redis-slave/
│       ├── deployment.yaml
│       └── service.yaml
└── deploy/              # Deployment configurations
    ├── conductor.yaml
    ├── build.sh
    ├── up.sh
    └── down.sh

Step-by-Step Walkthrough

1. Setup: Embedding Manifests

The first step is to embed your Kubernetes manifests using Go's embed directive:

package main

import (
    "context"
    "embed"
    "log"
    "os"

    "github.com/garunski/conductor-framework/pkg/framework"
)

//go:embed manifests
var manifestFS embed.FS

func main() {
    ctx := context.Background()

    cfg := framework.DefaultConfig()
    cfg.AppName = "guestbook-conductor"
    cfg.AppVersion = getVersion()
    cfg.ManifestFS = manifestFS
    cfg.ManifestRoot = "manifests"

    if err := framework.Run(ctx, cfg); err != nil {
        log.Fatalf("Error: %v", err)
    }
}

func getVersion() string {
    if v := os.Getenv("VERSION"); v != "" {
        return v
    }
    return "dev"
}

2. Manifests: Structure and Template Syntax

Manifests are organized by service in the manifests/ directory. Each service has deployment and service YAML files that use Go template syntax for parameter substitution:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{if .NamePrefix}}{{.NamePrefix}}-{{end}}frontend
  namespace: {{.Namespace}}
spec:
  replicas: {{.Replicas | default 1}}
  template:
    spec:
      containers:
      - name: frontend
        image: {{.ImageTag | default "latest"}}

Parameters are provided via the DeploymentParameters CRD or extracted from manifest defaults.

3. Parameters: Using DeploymentParameters CRD

Configure deployment parameters using a Kubernetes CRD:

apiVersion: conductor.io/v1alpha1
kind: DeploymentParameters
metadata:
  name: default
  namespace: default
spec:
  global:
    namespace: default
    replicas: 1
  services:
    redis:
      replicas: 3
      imageTag: "7.0"
    frontend:
      replicas: 2
      imageTag: "v5"

4. Running: Starting the Conductor

Build and run the conductor locally:

# Build
cd examples/guestbook-conductor
go build -o guestbook-conductor .

# Run
./guestbook-conductor

The conductor will:

  1. Load manifests from the embedded manifests/ directory
  2. Start a web server on port 8081 (configurable via PORT env var)
  3. Provide a web UI at http://localhost:8081
  4. Manage Kubernetes resources based on the manifests

5. Deployment: Using API/UI to Deploy Services

Deploy services using the REST API:

# Deploy all services
curl -X POST http://localhost:8081/api/up

# Deploy specific services
curl -X POST http://localhost:8081/api/up \
  -H "Content-Type: application/json" \
  -d '{"services": ["frontend", "redis-master", "redis-slave"]}'

Or use the Web UI at http://localhost:8081 to deploy, update, or remove services interactively.

6. Monitoring: Viewing Events and Health Status

Monitor your deployments:

# Get service health
curl http://localhost:8081/api/services/health

# Get events
curl http://localhost:8081/api/events?limit=10

# Get errors only
curl http://localhost:8081/api/events/errors

Workflow

The complete workflow from configuration to deployment:

Values (CRD/Defaults) → Templating → Manifests → Reconciliation → Kubernetes Resources
  1. Values: Parameters are defined in DeploymentParameters CRD or use framework defaults
  2. Templating: Go templates render manifests with parameter values and Sprig functions
  3. Manifests: Rendered Kubernetes YAML manifests are stored and indexed
  4. Reconciliation: Framework applies manifests to Kubernetes cluster via API
  5. Kubernetes Resources: Resources are created/updated in the cluster

Deploying to Kubernetes

You can also deploy the conductor itself to Kubernetes:

cd examples/guestbook-conductor/deploy
./up.sh

This will:

  1. Build the Docker image (if not already built)
  2. Deploy the conductor to the guestbook-conductor namespace
  3. Set up RBAC, PVC, and all necessary resources

To access the Web UI, port-forward the service:

kubectl port-forward -n guestbook-conductor svc/guestbook-conductor 8081:8081

Next Steps