Concourse Architecture

This topic isn't crucial to understanding Concourse; if you're just getting started and have finished the Installing section, you may want to first move on to Using Concourse.

Concourse is a fairly simple distributed system built up from the following components. You'll see them referenced here and there throughout the documentation, so you may want to skim this page just to get an idea of what they are.

tutorial image

ATC: web UI & build scheduler

The ATC is the heart of Concourse. It runs the web UI and API and is responsible for all pipeline scheduling. It connects to PostgreSQL, which it uses to store pipeline data (including build logs).

Multiple ATCs can be running as one cluster; as long as they're all pointing to the same database, they'll synchronize using basic locking mechanisms and roughly spread work across the cluster.

The ATC by default listens on port 8080, and is usually colocated with the TSA and sitting behind a load balancer.

Note: for intercept to function, make sure your load balancer is configured to do TCP or SSL forwarding, not HTTP or HTTPS.

TSA: worker registration & forwarding

The TSA is a custom-built SSH server that is used solely for securely registering workers with the ATC.

The TSA only supports two commands: register-worker and forward-worker.

The register-worker command is used to register a worker directly with the ATC. This should be used if the worker is running in the same (private) network as the ATC.

The forward-worker command is used to reverse-tunnel a worker's addresses through the TSA and register the forwarded connections with the ATC. This allows workers running in arbitrary networks to register securely, so long as they can reach the TSA. This is much safer than opening the worker up to the outside world.

The TSA by default listens on port 2222, and is usually colocated with the ATC and sitting behind a load balancer.

Workers: container runtime & cache management

Workers are machines running Garden and Baggageclaim servers and registering themselves via the TSA.

Workers have no important state configured on their machines, as everything runs in a container and thus shouldn't care about what packages are installed on the host (well, except for those that allow it to be a worker in the first place). This is very different from workers in other non-containerized CI solutions, where the state of packages on the worker is crucial to whether your pipeline works or not.

Each worker registers itself with the Concourse cluster via the TSA.

Workers by default listen on port 7777 for Garden and port 7788 for Baggageclaim. If they are within a private network reachable by the ATC, they'll probably bind on all addresses (0.0.0.0) and register themselves directly. Otherwise they should bind on 127.0.0.1 and forward themselves through the TSA.