Aquayman (A Quay Manager) allows you to declare your teams, robots and repository permissions in a declarative way (by virtue of a YAML file), which will then be applies to your Quay.io organization. This enables consistent, always up-to-date team members and access rules.
- Manages organization teams, robots and repository permissions.
- Exports the current state as a starter config file.
- Previews any action taken, for greater peace of mind.
We strongly recommend that you use an official release of Aquayman.
The code and sample YAML files in the main branch of are under active development and are not guaranteed to be stable. Use them at your own risk!
You can install/compile it directly if you have Go 1.20+ installed on your system:
go install github.com/kubermatic-labs/aquayman
Whenever Aquayman synchronizes an organization, it will perform these steps:
-
Ensure only the robots defined in the configuration file exist and that their description is up-to-date.
-
Ensure only the teams defined in the configuration file exist. For each team, adjust (add or remove) the members.
-
List all existing repositories and for each
- Find a matching repository configuration, based on the name. This can be either an exact match, or a glob expression match.
- If no configuration is found, delete the repository if Aquayman runs with
-delete-repos
. Otherwise leave the repository alone. - Otherwise, adjust the assigned teams and individual users/robots.
-
If running with
-create-repos
, list all configured repositories from the YAML file. Create and initialize all not yet existing repositories.
You need an OAuth2 token to authenticate against the API. In your organization settings
on Quay.io, you can create an application and for it you can then generate a token. Export
it as the environment variable AQUAYMAN_TOKEN
:
export AQUAYMAN_TOKEN=thisisnotarealtokenbutjustanexample
Except for the OAuth2 token, all configuration happens in a YAML file. See the annotated
config.example.yaml
for more information or let Aquayman generate a config for you by
exporting your current settings. See the next section for more information on this.
It's possible to only validate a configuration file for syntactic correctness by running
Aquayman with the -validate
flag:
aquayman -config myconfig.yaml -validate
2020/04/16 23:14:20 ✓ Configuration is valid.
Aquayman exits with code 0 if the config is valid, otherwise with a non-zero code.
To get started, Aquayman can export your existing Quay.io settings into a configuration file. For this to work, prepare a fresh configuration file and put your organisation name in it. You can skip everything else:
organization: exampleorg
Now run Aquayman with the -export
flag:
aquayman -config myconfig.yaml -export
2020/04/16 23:14:38 ► Exporting organization exampleorg
2020/04/16 23:14:38 ⇄ Exporting robots…
2020/04/16 23:14:39 ⚛ mybot
2020/04/16 23:14:39 ⇄ Exporting repositories…
2020/04/16 23:14:40 ⚒ myapp
2020/04/16 23:14:42 ⇄ Exporting teams…
2020/04/16 23:14:42 ⚑ owners
2020/04/16 23:14:43 ✓ Export successful.
Depending on your teams and repositories this can take a few minutes to run. Afterwards the
myconfig.yaml
will have been updated to contain an exact representation of your settings:
organisation: exampleorg
teams:
- name: owners
role: admin
members:
- exampleorg+mybot
repositories:
- name: myapp
teams:
owners: admin
robots:
- name: mybot
description: Just an example bot.
Synchronizing means updating Quay.io to match the given configuration file. It's as simple as running Aquayman:
aquayman -config myconfig.yaml
2020/04/16 23:32:00 ► Updating organization exampleorg…
2020/04/16 23:32:00 ⇄ Syncing robots…
2020/04/16 23:32:00 ✎ ⚛ mybot
2020/04/16 23:32:01 - ⚛ thisbotshouldnotexist
2020/04/16 23:32:01 ⇄ Syncing teams…
2020/04/16 23:32:01 ✎ ⚑ owners
2020/04/16 23:32:01 + ♟ exampleorg+mybot
2020/04/16 23:32:01 ⇄ Syncing repositories…
2020/04/16 23:32:02 ⚠ Run again with -confirm to apply the changes above.
Aquayman by default only shows a preview of things it would do. Run it with -confirm
to let
the magic happen.
aquayman -config myconfig.yaml -confirm
2020/04/16 23:32:10 ► Updating organization exampleorg…
2020/04/16 23:32:10 ⇄ Syncing robots…
2020/04/16 23:32:10 ✎ ⚛ mybot
2020/04/16 23:32:11 - ⚛ thisbotshouldnotexist
2020/04/16 23:32:11 ⇄ Syncing teams…
2020/04/16 23:32:11 ✎ ⚑ owners
2020/04/16 23:32:11 + ♟ exampleorg+mybot
2020/04/16 23:32:11 ⇄ Syncing repositories…
2020/04/16 23:32:12 ✓ Permissions successfully synchronized.
Note that repositories by default can freely exist without being configured in Aquayman.
This is meant as a safe default, so introducing Aquayman in an existing organiztion is
easier. To fully synchronize (delete dangling and create missing) repositories, run
Aquayman with -create-repos
and -delete-repos
.
If you encounter issues file an issue or talk to us on the #kubermatic-labs channel on the Kubermatic Slack.
Thanks for taking the time to join our community and start contributing!
Feedback and discussion are available on the mailing list.
- Please familiarize yourself with the Code of Conduct before contributing.
- See CONTRIBUTING.md for instructions on the developer certificate of origin that we require.
- We welcome pull requests. Feel free to dig through the issues and jump in.
See the list of releases to find out about feature changes.