GMP-CONCOURSE-0001 - Concourse 4 Upgrade


Concourse Genesis Kit v3.0.0 is the first kit that crosses the barrier from Concourse version 3 to 4. This carries with it some underlying changes to the way authorization works in Concourse. While the kit provides a reasonable layer of abstraction for most of these changes, you may still need to make changes to your existing Concourse deployment in order for the migration to go cleanly.


If your configuration fulfills any of the following criteria, then the database migration associated with this upgrade will fail:

Things that should not affect this migration:

Additionally, teams that are configured with basic auth will need to have their users added manually using the add_local_users property of the ATC. The user named concourse that is configured with the kit in Vault will be seeded for you automatically.

The Process

Take a Backup

First off, take a backup of the atc database. If you don't already have SHIELD doing that, then consider having SHIELD do that. If for some reason that isn't an option, you can use the pg_dump at /var/vcap/packages/postgres-<version-number>/bin/pg_dump on the db node to create a backup.

Basically, if you miss a step and the migration fails, it'll be nice to be able to fall back to the previous kit version and slap the backup in place.

As an aside, if you have configured a SHIELD backup for this node, you may need to change your pg_bindir property of your target after the upgrade, as the Postgres folder will change paths due to the Postgres upgrade.

Checking if you have a problem to fix

For starters, if you only have one team then you don't have a problem. Stop reading and do the migration.

If you're still reading, then it's time to get on the Concourse db VM and take a look at the ATC database. SSH in:

bosh -e <your-env> -d <your-concourse-deployment> ssh db

PSQL into the DB:

/var/vcap/packages/postgres-<your-postgres-version>/bin/psql -U atc

Get the team configurations:

select * from teams;

If any of the teams auth configurations fulfill the qualities described in the Impact section, you'll need to reconfigure your teams using the Fly CLI.

Fixing your configuration with the Fly CLI

Target your Concourse's main team with Fly, and for each team take the action related to your issue. All of these will need to be done with set-team. Properties are not upserted, so when calling set-team, make sure you provide the entire team configuration.

Seeding local users

If you have basic auth users other than the default concourse user, then you'll need seed them into the ATC manually in the environment manifest.

- name: web
  - name: atc
      - (( append ))
      - username:$2$12$bcryptOfPassword
      - username2:$2$12$bcryptOfPassword2

If you want an easy way to make the bcrypts of each password, put them in the Vault with safe and use safe fmt bcrypt to make a bcrypt for each.

Help & Support

If you have concerns about the impact of this migration process, or need assistance running through it, please don't hesitate to find us in #help on Slack.