Concourse
=========

Manages all parts of [Concourse](CONCOURSE), including web nodes, worker
nodes, and databases.

Usage
-----

### Overview
Concourse is configured as a set of clusters. ach cluster consists of

- 1 database (a database within PostgreSQL)
- 1 or more worker nodes
- 1 load balancing nginx
  (this is needed for also a single node, due to how this module is written).
- 1 or more worker nodes

### Keys

There are also a number of [different keys](https://concourse-ci.org/concourse-generate-key.html)
needed for concourse to operate correctly.

These are

- The session signing key, used by the web node for signing user session tokens.
- the TSA host key, used by worker nodes to verify their connection to the web node
- The worker keys, simple ssh keys used by the nodes when connecting.

The session signing key, and the TSA host key are **NOT** managed by this
module. This since they need to be the same for all nodes in a cluster (and
there isn't a good way to mark a single node as the "master" without extra
work, which might as well be used for manually generating the keys).

The worker keys *are* however managed by this module. Each worker
generates its own key, and then creates an exported resource which
each web node realizes. (this is bounded to within the cluster).

### Example Configuration

A complete concourse configuration might look like this.

Note that the `session_signing_key`, `tsa_private_key`, and `tsa_public_key` is
found through Hiera in this example, as explained under [Keys](#Keys).

```puppet
$cluster = 'default'
$external_domain = 'concourse.example.com'

# Cluster configuration should be set on the main resource. All other resources
# references this hash, referenced by the cluster parameter.
class { 'concourse':
  default_cluster => $cluster,
  clusters        => {
    $cluster => {
      'postgres_user'       => 'concourse',
      'postgres_password'   => 'CHANGEME',
      'external_url'        => "https://${external_domain}",

      # Keys are gotten through Hiera here.
      'session_signing_key' => lookup('session_signing_key'),
      'tsa_private_key'     => lookup('tsa_private_key'),
      'tsa_public_key'      => lookup('tsa_public_key'),
    }
  }
}

# Creates the database and user.
# Omit this if managing the database elsewhere
concourse::database {
  cluster => $cluster,
}

# Configures the load balancer.
# Should only be done once for the cluster
# (unless you load balance you load balancers...)
#
# ensure that `nginx::stream` is set to true.
concourse::proxy::nginx { $external_domain:
  cluster => $cluster,
}

# Configures a web node, and attach it to the cluster.
# Note that multiple web nodes in the same cluster should have identical
# configurations (except for their peer_address).
# Note that concourse currently always bind to port 8080.
class { 'concourse::web':
  cluster => $cluster,
}

# Some authentication method needs to be configured. The authentication happens
# in the web nodes (although an extra layer could be added through nginx).
# Check the `concourse::auth::` module for available methods.
#
# The simplest is `concourse::auth::local`:
class { 'concourse::auth::local':
  users => [
    {
      'name'     => 'hugo',
      'password' => 'This password is stored in cleartext',
    }
  ]
}

# Configure a worker node, and also attach that to the cluster.
class { 'concourse::worker':
  cluster => $cluster,
}

# Finally, this installs the fly cli.
include concourse::fly
```

Note that only some keys are managed through the
`concourse::configured_clusters`, and for Hiera is *strongly* recommended for
more advanced setups with multi-node clusters.

### Nodes
As mentioned above, a concourse cluster contains a number of different roles
(here called nodes). A short summary of each node.

#### Web node
Web nodes acts as the front-end, and dispatcher.

Each web node is stateless, and manages its state through a shared
database. If multiple nodes are used, then a
[web node cluster](#web node cluster)
should be used.

(technically clusters are always used, and default to the cluster "default").

##### Authentication

TODO

#### Worker Node

TODO

#### Database

TODO

#### Fly Client

TODO

#### Web node cluster

TODO


### Special Hiera Keys

TODO

```yaml
concourse::${cluster}:
    postgres_user: pg_username
    postgres_password: pg_password
    session_signing_key: 'A valid key'
    tsa_private_key: 'A valid key'
    tsa_public_key: 'A public key matching the private key'
```

[CONCOURSE]: https://concourse-ci.org/