search

cncf / clowarden

CLOWarden is a tool that manages access to resources across multiple services
https://clowarden.io
Apache License 2.0
39 stars 5 forks source link

Clarify where CLOWarden organization config must be located #222

Closed justaugustus closed 4 days ago

justaugustus commented 5 days ago

(Apologies if this is already specified somewhere and I've missed it.)

Looking at a few repos leveraging CLOWarden, I've noticed that it's not exactly clear if there's a convention for where a config file must be location or what it should be named:

A few questions / documentation requests:

Separately (for my own education as a Rust newbie), could you point me to the codepaths that govern how this configuration is found/used?

cc: @lelia

justaugustus commented 5 days ago

cc: @cynthia-sg @tegioz

tegioz commented 5 days ago

Hi @justaugustus

Some context first that I think will clarify most of your questions 🙂

CLOWarden wasn't/isn't actually meant to be a public GitHub application. Unlike GitVote (another GitHub app we've built you may be familiar with), where any user/org can install it and configure it by placing a .gitvote.yml file in certain locations, CLOWarden requires organizations to be registered on the server side.

The reason it works that way is because CLOWarden was designed to handle resources for multiple services, not just GitHub. You can see this in the code by looking at some "interfaces", like ServiceHandler, and the only implementation available so far, GitHub. Being able to create users, groups, etc, in other services would require credentials for each installation. So keeping that kind of configuration committed to a repository wasn't an option.

So GitHub is the first service supported, in addition to being the "user interface" to manage file. But others would come afterwards (although for one reason or another we haven't got there yet 😉).

In addition to this, the CLOWarden GitHub app requires some sensitive permissions to operate and, IMHO, it's not a good idea that a single entity handles keys (GitHub app credentials) that can be used to manage users, teams and permissions across multiple organizations. Based on this, CLOWarden wasn't meant to support more than one organization per deployment originally, as it was meant to only serve the CNCF organization (it was an experiment to replace Sheriff actually). Eventually, some other LF foundations/projects were interested in CW as well, so we added support for multiple organizations within a single deployment. But the intention was still to keep it scoped to a small set of closely related organizations.

Hopefully now everything should make a bit more sense. Let's go with the questions! (I'll better jump to a new comment 😉)

tegioz commented 5 days ago

The CLOWarden configuration is divided in two parts, the server side configuration and the organizations permissions configuration.

In the server side configuration you can define the organizations you'd like to manage from this deployment. You can see an example in the chart's README file. The repository where the permissions configuration will be located can be defined per organization, so you are free to pick the one you prefer. This is usually setup once and no more changes to it are needed unless you want to add support for more organizations.

Most of the activity happens in the organization's permissions configuration. You can see the CNCF's one as an example, and you can find more details about its format and how it works in the CLOWarden's repository README file.

clowarden-cli generate is meant to be used to generate an organization's permissions file, not the server side configuration, which is usually minimal and needs to be written manually.

You can find more information about the types that cover both configurations in the following locations:

https://github.com/cncf/clowarden/blob/4e5c0a0184b0b123f62c8f9f85b77fe0c36c31a4/clowarden-core/src/cfg.rs#L5-L14 https://github.com/cncf/clowarden/blob/4e5c0a0184b0b123f62c8f9f85b77fe0c36c31a4/clowarden-core/src/directory/legacy.rs#L201-L214 https://github.com/cncf/clowarden/blob/4e5c0a0184b0b123f62c8f9f85b77fe0c36c31a4/clowarden-core/src/services/github/legacy.rs#L15-L20 https://github.com/cncf/clowarden/blob/4e5c0a0184b0b123f62c8f9f85b77fe0c36c31a4/clowarden-core/src/services/github/state.rs#L489-L502

I can explain some other day about the legacy files if you'd like, it has its history as well 😉

I think this should cover all your questions, hope it helps! It's been indeed useful to me to remind where it came from and why some decisions were made 😊 We built it in a couple of months as an experiment to replace Sheriff (right before jumping into building the new landscape!), we gave it a try it one day and it's been working mostly fine since then with minimal maintenance. But it probably needs some touches here and there to make it easier to deploy and operate.

If you find any rough edges when deploying it please let us know and we'd be happy to clarify anything you need 👋

justaugustus commented 5 days ago

@tegioz — thanks for providing all of this context!

I think I still have some of the same questions 😅

Is the config file required to have a specific name?

Based on the examples I've seen in other repos, this does not appear to be a requirement.

Config is defaulted to config.yaml: https://github.com/cncf/clowarden/blob/4e5c0a0184b0b123f62c8f9f85b77fe0c36c31a4/clowarden-cli/src/main.rs#L65

Does CLOWarden require the config file to be located at the top level of the repo?

Unclear. This has to do with whether the code will properly traverse the directory structure past the top level.

What happens if there are other, non-CLOWarden-related YAML files in the same [sub]directory as the CLOWarden config?

It appears that this would not be relevant, since the legacy config file location would be explicitly specified (or defaulted) within the CLOWarden server configuration

clowarden-cli generate --org <org> --output-file <filename> currently outputs a config without organizations specified. Does that work? (Every config I've found listed above specifies organizations.)

It appears that clowarden-cli generate would generate an invalid org config file, unless organizations is a field that could be inferred from the server config.

tegioz commented 5 days ago

I think I still have some of the same questions 😅

No problem, let me try again 🙂

Is the config file required to have a specific name?

(I'm guessing the one you are interested is the config file where the teams and permissions are defined - I'll call it permissions file going forward for simplicity)

No, it can have any name and be located in any repo. That information will be defined per organization in the server configuration file.

permissions_config_location

Does CLOWarden require the config file to be located at the top level of the repo?

Unclear. This has to do with whether the code will properly traverse the directory structure past the top level.

No, you can provide the full path to the file in the server configuration. The file contents are fetched using the GitHub API, the repository is not cloned.

What happens if there are other, non-CLOWarden-related YAML files in the same [sub]directory as the CLOWarden config?

It appears that this would not be relevant, since the legacy config file location would be explicitly specified (or defaulted) within the CLOWarden server configuration

That's right, that wouldn't be a problem 👍

clowarden-cli generate --org <org> --output-file <filename> currently outputs a config without organizations specified. Does that work? (Every config I've found listed above specifies organizations.)

It appears that clowarden-cli generate would generate an invalid org config file, unless organizations is a field that could be inferred from the server config.

Oh I see the confusion here, my bad 😅

You may have noticed that the CNCF permissions file has a field named organization (singular). That's a Sheriff thing that hasn't been removed yet, but it has no meaning to CLOWarden, it's ignored.

On the CLOWarden server configuration, there is an organizations field (plural), which is the one I thought you meant in your first comment.

Please let me know if something doesn't make sense yet, happy to help 🙂

justaugustus commented 5 days ago

Thanks for the quick responses, @tegioz! Let me do some testing and I'll see if I have follow-up questions :)

tegioz commented 4 days ago

Will close this issue for now, please feel free to reopen if needed 🙂