From f7c2a761525075d0e67aa76ac42c69f332f02bfb Mon Sep 17 00:00:00 2001 From: Robert Kielty Date: Wed, 5 Jul 2023 10:57:47 +0100 Subject: [PATCH] adds deployment status and minor doc updates (#73) * adds deployment status and minor doc updates Signed-off-by: Robert Kielty * fixa typo GiHub -> GitHub Signed-off-by: Robert Kielty --------- Signed-off-by: Robert Kielty --- README.md | 39 ++++++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 76cba1d..058db57 100644 --- a/README.md +++ b/README.md @@ -2,21 +2,22 @@ [![CI](https://github.com/cncf/clowarden/actions/workflows/ci.yml/badge.svg)](https://github.com/cncf/clowarden/actions/workflows/ci.yml) -**CLOWarden** is a tool that automatically manages organizations users, teams and other resources across multiple services. +**CLOWarden** is a tool that manages the access to resources across multiple services with the initial focus on repositories in a GitHub organization. +CLOWarden allows you to grant access to an individual user or a defined team of users by submitting a PR to a file that defines access rules. -The CNCF has recently begun to use [Sheriff](https://github.com/cncf/sheriff) to manage people-related resources. CLOWarden is an *experiment* to replace Sheriff with a system that suits better the needs of the CNCF. +The CNCF initially used [Sheriff](https://github.com/cncf/sheriff) to manage access to resources. CLOWarden has replaced Sheriff with a system that suits better the needs of the CNCF. -To facilitate experimentation and make a potential transition easier, CLOWarden supports a legacy configuration mode that allows using [a subset of the Sheriff's permissions configuration file](#configuration) and the [CNCF's people file](https://github.com/cncf/people/blob/main/people.json) to define resources like users, teams and GitHub repositories (the same files currently used by CNCF at ). +CLOWarden supports a legacy configuration mode that allows using [a subset of the Sheriff's permissions configuration file](#configuration) and the [CNCF's people file](https://github.com/cncf/people/blob/main/people.json) to define users, teams and GitHub repositories (the same files currently used by CNCF at ). ## How it works CLOWarden's main goal is to ensure that the resources' **desired state**, as defined in the configuration files, matches the **actual state** in the corresponding services. This is achieved by running *reconciliation* jobs, that can be triggered *on-demand* or *periodically*. These reconciliation jobs are in charge of applying the necessary changes to address the differences between the desired and actual state on each service, which is done by delegating some work on specialized *service handlers*. -CLOWarden monitors pull requests created in the configuration repository and, when applicable, it validates the proposed changes and creates reconciliation jobs to apply the necessary changes. This is what we call an on-demand reconciliation job: it's created as a result of a user's action, and changes are applied *immediately* once the pull request is merged. +CLOWarden monitors pull requests created in the configuration repository and, when applicable, it validates the proposed changes to access rules and creates reconciliation jobs to apply the necessary changes. This is what we call an on-demand reconciliation job: it's created as a result of a user's submitted pull request, and changes are applied *immediately* once the pull request is approved and merged. ![reconciliation-completed-success](docs/screenshots/reconciliation-completed-success.png) -Sometimes, however, this may not be enough. Changes can be applied manually to the service bypassing the configuration files (i.e. from the GitHub settings UI), and CLOWarden still needs to make sure that the actual state matches the desired state. So in addition to on-demand reconciliation jobs, CLOWarden runs *periodic* ones to ensure everything is all right all the time. +Sometimes, however, this may not be enough. Changes can be applied manually to the service bypassing the configuration files (i.e. from the GitHub settings UI), and CLOWarden still needs to make sure that the actual state matches the desired state documented in the configuration files. So in addition to on-demand reconciliation jobs, CLOWarden runs *periodic* ones to ensure everything is all right all the time. ### State @@ -32,11 +33,13 @@ Let's go through a full example to see how this would work in practice. Our goal in this example will be to create a new team (named `team1`) with one maintainer and one member, as well as a new repository (named `repo1`). We want to give `team1` write permissions on `repo1`, and we'd also like to add a external collaborator, named `collaborator1`, with read permissions. -The first step will be to create a pull request to add the entries below to the configuration files (*please note that we are intentionally introducing an error in this code snippet -misspelled team1-*): +The first step will be to create a pull request to add the entries below to the configuration files + +(*This configuration intentionally introduces a typo so we can describe CLOWarden's PR validation checks -team1 is misspelled-*): ```yaml teams: - - name: tem1 + - name: tem1 # This is a deliberate typo. The value should be "team1" not "tem1" maintainers: - maintainer1 members: @@ -47,21 +50,21 @@ teams: repositories: - name: repo1 teams: - team1: write + team1: write # team1 does not exist! The CLOWarden validation check will report an error in a PR as a comment external_collaborators: collaborator1: read visibility: public ``` -As soon as the pull request is created, CLOWarden will detect it and will proceed to **validate** the changes proposed. +As soon as the pull request is created, CLOWarden **validates** the changes proposed. -One of CLOWarden goals is to try to make it *as simple as possible for maintainers to review and approve suggested changes* to the configuration. To do that, CLOWarden provides feedback in pull requests in the form of comments. Suggested changes can be invalid for a number of reasons, like a syntax problem in the configuration file, or not following any of the rules, like using an invalid role when defining permissions. CLOWarden tries its best to give helpful feedback to the pull request creator, to point them in the right direction and help address errors without requiring the maintainers intervention. +One of the goals of CLOWarden is to make it *as simple as possible for maintainers to review and approve suggested changes* to the configuration. To do that, CLOWarden provides feedback in pull requests in the form of comments. Suggested changes can be invalid for a number of reasons, like a syntax problem in the configuration file, or not following any of the rules, like using an invalid role when defining permissions. CLOWarden tries its best to give helpful feedback to the pull request creator, to point them in the right direction and help address errors without requiring the maintainers intervention. -In this case, the error we introduced intentionally was catched: we incorrectly defined the new team as `tem1`, but then used it as `team1` in the repository definition. +In this case, the error we introduced intentionally was caught: we incorrectly defined the new team as `tem1`, but then try to reference it as `team1` in the repository access definition. ![validation-error](docs/screenshots/validation-error.png) -If this error hadn't been catched at validation time, a team named `tem1` would have been created and the process of granting permissions to `team1` on `repo1` would have failed as `team1` wouldn't exist. +If this error had not been caught at validation time, a team named `tem1` would have been created and the process of granting permissions to `team1` on `repo1` would have failed as `team1` wouldn't have existed. Please note that, in addition to the feedback comment, CLOWarden created a **check** in the PR to indicate that the configuration changes are not valid. When used in combination with branch protection, this can help prevent that invalid configuration changes are merged. @@ -73,7 +76,9 @@ The pull request creator can now push a fix to address these issues. Once that's Now CLOWarden is happy with the changes proposed! This time, it also tried to help the maintainer who will approve the changes by describing in the comment what had changed. -Sometimes this may be easy to spot by just looking at the files diff. But in other occasions, depending on the changes applied, it can get trickier and be error prone, as just a single extra space or tabulation can have unintented consequences. So CLOWarden tries to simplify this by analyzing the changes itself and displaying them in an easy to read way. +Sometimes this may be easy to spot by just looking at a the diff on the PR. But on other occasions, depending on the changes applied, it can get trickier and be error prone, as just a single extra space or tabulation can have unintented consequences. So CLOWarden simplifies this by analyzing the changes itself and displaying them in an easy to read way as a comment on the PR. + +Outside of the context of a PR it is possible to view an autdit log of the changes made see the [#Audit tool](Audit tool) below ![valid-config-check-run](docs/screenshots/valid-config-check-run.png) @@ -87,9 +92,9 @@ In this case all changes were applied successfully, but if something would have CLOWarden registers all changes applied to the services in a database. Even though most of the time all information related to a given change will be accessible on the PR that triggered it, sometimes it may be necessary to go a bit further to answer questions like: -- *When was user1 granted access to repository1 and who approved it?* -- *In what PR was team1 removed?* -- *What changes have been applied by automatic periodic reconciliations during the last 24 hours?* +- *When* was user1 *granted access* to repository1 and *who approved granting that access*? +- In what PR was *team1 removed?* +- What changes have been applied *by automatic periodic reconciliations* during the *last 24 hours?* To help to answer these questions quickly, CLOWarden provides an audit tool that allows maintainers to easily search and inspect applied changes. The audit tool can be accessed by using a web browser and is available at: `https://YOUR-CLOWARDEN-URL/audit/`. @@ -189,7 +194,7 @@ It's important to keep in mind that.. ## Using CLOWarden in your organization -CLOWarden is still in an experimental phase and breaking changes are expected, so we do not recommend to use it in production enviroments yet. Once it stabilizes, we'll publish some additional documentation to make it easier to run your own CLOWarden instance. +Although has been deployed for use in the CNCF GitHub org, CLOWarden is still in an experimental phase and breaking changes are expected, so we do not recommend its use in other production enviroments yet. Once it stabilizes, we'll publish some additional documentation to make it easier to run your own CLOWarden instance. ## Contributing