Deployment Modes Reference - Concourse CI Machine Charm

Overview

The Concourse CI Machine Charm supports three deployment modes, controlled by the mode configuration option. Each mode determines the role of a unit (web server or worker) and affects key distribution, scaling behavior, and resource requirements.

Note: The mode configuration is set at deployment time and cannot be changed dynamically. To change modes, deploy a new application with the desired mode.

Mode Specifications

auto (Recommended)

Default Yes

Leader Behavior Web Server

Follower Behavior Worker

Minimum Units 2 (1 web + 1 worker)

Key Distribution Automatic (peer relation)

Description: Leader unit runs web server, non-leader units run workers. Keys are automatically distributed via peer relations with zero manual intervention.

Use Cases:

Production deployments requiring scalability
Multi-unit deployments with automatic role assignment
Environments where workers scale independently of web server
Default choice for most deployments

Best Practice: This is the recommended mode for production. Deploy with -n 3 (1 web + 2 workers) for high availability.

Example Deployment:

juju deploy concourse-ci-machine concourse-ci -n 3 --channel edge --config mode=auto
juju integrate concourse-ci:postgresql postgresql:database

Result:

concourse-ci/0 (leader): Web server with UI, API, TSA, and scheduler
concourse-ci/1: Worker node
concourse-ci/2: Worker node

web

Default No

Component Web Server Only

Typical Units 1

Key Distribution Via tsa relation

Description: Unit runs only the web server (UI, API, TSA, scheduler). Requires separate worker application connected via tsa relation.

Use Cases:

Independent scaling of web and worker resources
Dedicated web server with separate worker pools
Specialized worker configurations (GPU, high-memory, etc.)
Multi-application architectures

Example Deployment:

juju deploy concourse-ci-machine web --channel edge --config mode=web
juju deploy concourse-ci-machine worker -n 2 --channel edge --config mode=worker
juju integrate web:postgresql postgresql:database
juju integrate web:tsa worker:flight

Result:

web/0: Web server only
worker/0, worker/1: Workers connected via TSA

Note: The tsa / flight relation automatically handles SSH key exchange between web and worker applications.

worker

Default No

Component Worker Only

Typical Units 2+

Key Distribution Via flight relation

Description: Unit runs only the worker component. Connects to web server via flight relation to retrieve TSA keys and register with scheduler.

Use Cases:

Paired with mode=web for independent scaling
GPU workers with specialized hardware
Workers with custom tags for job targeting
Workers in different availability zones or regions

Example Deployment:

juju deploy concourse-ci-machine worker -n 2 --channel edge --config mode=worker
juju integrate worker:flight web:tsa

Warning: Worker mode requires a separate web server application. Workers cannot function without connecting to a web server via the flight relation.

GPU Worker Example:

juju deploy concourse-ci-machine gpu-worker --channel edge \
  --config mode=worker \
  --config compute-runtime=cuda \
  --config tag="cuda,gpu"

Mode Comparison Table

Feature	auto	web	worker
Web Server	Leader only	Yes	No
Worker	Non-leaders	No	Yes
Min Units	2	1	1
Scalability	High (add units)	Medium (separate apps)	High (add units)
Key Distribution	Automatic (peers)	Via tsa relation	Via flight relation
PostgreSQL Required	Yes	Yes	No
Production Ready	✅ Yes	✅ Yes	✅ Yes
Use Case	Default production	Independent scaling	Specialized workers

Scaling Behavior

auto Mode Scaling

# Start with 3 units (1 web + 2 workers)
juju deploy concourse-ci-machine concourse-ci -n 3 --channel edge --config mode=auto

# Add 2 more workers (total: 1 web + 4 workers)
juju add-unit concourse-ci -n 2

Each new unit automatically becomes a worker. Leader remains web server.

web + worker Mode Scaling

# Scale workers independently
juju add-unit worker -n 3

# Web server typically remains at 1 unit (HA not yet supported)

Workers scale independently from web server. Web server does not scale horizontally (single leader).

Key Distribution Mechanisms

Mode	Mechanism	Keys Exchanged	Manual Setup
`auto`	Peer relation	TSA host key, TSA public key, worker private key	None (automatic)
`web`	`tsa` relation (provides)	TSA host key, TSA public key	None (automatic)
`worker`	`flight` relation (requires)	Worker public key (sent to web)	None (automatic)

Best Practice: All modes handle key distribution automatically. No manual key copying or configuration required.

Deployment Recommendations

Scenario	Recommended Mode	Reasoning
Production CI/CD	`auto`	Simplest production setup with automatic scaling and key management
GPU Workers	`web` + `worker`	Separate worker pools for GPU and CPU workloads
High Traffic	`auto` (n≥5)	Scale workers to handle increased job throughput
Development	`auto` (n=2)	Minimal resource usage for testing (1 web + 1 worker)
Multi-Region	`web` + `worker` (multiple)	Deploy workers in different regions/zones

Constraints and Limitations

auto Mode

Requires minimum 2 units for functional workers (unit 0 becomes web)
Leader election: If leader unit is removed, Juju elects new leader (becomes web server, old leader becomes worker if still present)
Cannot run web server on non-leader units

web Mode

Requires PostgreSQL relation (blocked status without it)
Does not support horizontal scaling (single web server only)
Must be paired with worker mode units for job execution

worker Mode

Requires flight relation to web server (blocked status without it)
Cannot function independently (no scheduler, no API)
Worker tags must be unique if targeting specific jobs

Note: The mode configuration is immutable after deployment. To change modes, you must deploy a new application with the desired mode and migrate pipelines.