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:
- 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.
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.
instance_groups: - name: web jobs: - name: atc properties: add_local_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
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.