Introducing Aquayman

At Kubermatic we are using Quay.io to host our various Docker repositories. Over the last few years, cruft accumulated and we noticed that keeping team memberships up-to-date as employees and customers change became a hassle.

For Github we already make use of Peribolos, a wonderful tool to manage your Github organization declaratively. For quay we unfortunately did not find an equivalent solution, so we made our own.

Say hello to Aquayman (short for “A Quay Manager”). It allows you to manage teams, memberships and robot accounts for your organization by just editing a single YAML file.

To get started, it’s best to download the latest release and export your current configuration (not just as a starting point, but also as a backup):

$ wget https://github.com/kubermatic-labs/aquayman/releases/download/v0.1.2/aquayman_0.1.2_linux_amd64.zip
$ unzip aquayman_0.1.2_linux_amd64.zip aquayman

# prepare your configuration file by setting the org name
$ echo "organization: mytestorg" > mytestorg.yaml

# use Aquayman to dump your existing configuration
$ ./aquayman -config mytestorg.yaml -export
2020/05/14 13:56:55 ► Exporting organization mytestorg…
2020/05/14 13:56:55 ⇄ Exporting robots…
2020/05/14 13:56:56   ⚛ drone
2020/05/14 13:56:57   ⚛ netlify
2020/05/14 13:56:58 ⇄ Exporting repositories…
2020/05/14 13:56:59   ⚒ myapp
2020/05/14 13:56:59   ⚒ secretapp (private)
2020/05/14 13:57:00 ⇄ Exporting teams…
2020/05/14 13:57:00   ⚑ owners
2020/05/14 13:57:02   ⚑ developers
2020/05/14 13:57:03   ⚑ customers
2020/05/14 13:57:05 ✓ Export successful.

Your mytestorg.yaml will now be updated and look something like this:

organization: mytestorg
teams:
  - name: owners
    role: admin
    members:
      - xrstf

  - name: developers
    role: creator
    members:
      - scheeles
      - kdomanski

  - name: customers
    role: creator
    members:
      - mytestorg+initech
      - mytestorg+omniconsumerproducts

repositories:
  - name: myapp
    teams:
      developers: write
      customers: read

  - name: secretapp
    users:
      xrstf: write

robots:
  - name: initech
    description: Personal Account for Peter Gibbons

  - name: omniconsumerproducts
    description: "Contact person: Dick Jones"

(The Aquayman repository contains a documented example configuration.)

If you start with an existing, messy organization, your next step will probably be to clean up your configuration a bit. Once you are satisfied, you can apply the configuration:

$ ./aquayman -config mytestorg.yaml
2020/05/14 13:57:55 ► Updating organization mytestorg…
2020/05/14 13:57:55 ⇄ Syncing robots…
2020/05/14 13:57:56   + ⚛ drone
2020/05/14 13:57:57   + ⚛ netlify
2020/05/14 13:57:58 ⇄ Syncing repositories…
2020/05/14 13:57:59   ✎ ⚒ myapp
2020/05/14 13:57:59   ✎ ⚒ secretapp (private)
2020/05/14 13:58:00 ⇄ Syncing teams…
2020/05/14 13:58:00   ✎ ⚑ owners
2020/05/14 13:58:02   ✎ ⚑ developers
2020/05/14 13:58:03   ✎ ⚑ customers
2020/05/14 13:58:05 ⚠ Run again with -confirm to apply the changes above.

Aquayman shows you a diff-style output, hinting at the actions it would perform. If you are once again happy, you can run it again with the -confirm flag.

$ ./aquayman -config mytestorg.yaml
2020/05/14 13:58:55 ► Updating organization mytestorg…
...magic happens...
2020/05/14 13:59:05 ✓ Permissions successfully synchronized.

Congratulations, time to grab a coffee!

At Kubermatic we manage our configuration in Github, so we get a nice review-workflow whenever permissions need to change, have an audit trail and can restrict the permissions to manage our organization even further. The less human intervention needed, the better.