Overview

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.

Impact

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

• Two teams are configured with the same basic auth username
• Two teams are configured with Github Auth, but they point to different OAuth applications within Github.
• Two teams are configured with Github Auth, but they point to different Github instances (e.g. public Github and an enterprise deployment, or two enterprise deployments)
• Two teams are configured with CF Auth, but they point to different Cloud Foundry deployments
• If you're using Bitbucket auth - sorry, it's not supported in Concourse 4. You'll need to consider a different authentication type.

Things that should not affect this migration:

• Two teams are configured with Basic auth, but they have different users.
• Two teams are configured with Github auth against the same OAuth provider, but they check for membership of different orgs or teams.
• Two teams are configured with CF Auth against the same Cloud Foundry but verify different space membership.

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.

• If multiple teams have the same basic auth user, change all but one of the team's users to a different username using the --basic-auth-* flags. You can always change it back after the migration.
• If teams reference different Github OAuth applications, migrate them all to using one with the --github-auth-* flags. You may need to grant the OAuth app access to query org or team membership in orgs with more secretive privacy settings. This is something that can be done after the migration is finished. You may also want to revoke all user tokens from the OAuth application you're migrating to - if users only allowed the application access to view the organizations revelant to that particular application's domain, then they will not get authorized for non-granted domains. Revoking their token will give them a chance to grant more access to the OAuth app, as it will cause them to go through the initial authorization flow again.
• If you can't merge OAuth applications, or you're referencing multiple Github instances, then you'll need to make separate Concourse deployments for each unmergeable zone.
• For CF, if you're referencing multiple Cloud Foundries, you'll need a separate Concourse deployments for each Cloud Foundry you want to auth to.

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.

instancegroups: - name: web jobs: - name: atc properties: addlocal_users: - (( 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.