Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update group docs to describe subgroups and inherited roles #3824

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 38 additions & 2 deletions docs/concepts-basics/building-blocks/groups.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,41 @@
# Groups

_Groups_ are made up of users who have roles. An organization can have one or more groups. Each project can be assigned one or more groups. Groups can be assigned to multiple projects. Groups are created independently of projects, and then assigned to them.
_Groups_ are made up of users who have roles.
An organization can have one or more groups.
Each project can be assigned one or more groups.
Groups can be assigned to multiple projects.
Groups are created independently of projects, and then assigned to them.

Organizations have a quota to limit the number of groups assigned to it. If you need to change the quota, please contact {{ defaults.helpstring }}.
Organizations have a quota to limit the number of groups assigned to it.
If you need to change the quota, please contact {{ defaults.helpstring }}.

# Subgroups

!!! warning
Subgroups and not commonly used in Lagoon, and you probably don't need them.
shreddedbacon marked this conversation as resolved.
Show resolved Hide resolved
However, they can be useful in some rare situations.

!!! note
Subgroups are not exposed by the Lagoon UI or Lagoon CLI, but can be created through the Lagoon GraphQL API.

Groups can be nested to an arbitrary depth.
Subgroups are groups which are a child of another group.

Comment on lines +23 to +25
Copy link
Member

@tobybellwood tobybellwood Oct 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Groups can be nested to an arbitrary depth.
Subgroups are groups which are a child of another group.
Subgroups cannot be created or managed via the UI or the CLI; they will only be created via the legacy automated user sync tooling.
Groups can be nested to an arbitrary depth.
Subgroups are groups that are a child of another group.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They can be created via the API, but not the CLI

Subgroups cannot be created or managed via the UI or the API

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great, I knew I wasn't the only one confused about subgroups!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a note, hopefully that helps?

A user's role in an ancestor group is inherited by descendant groups.

## Subgroups example
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Subgroups example
## Subgroups explainer

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that "explainer" is clearer than "example" (is it even a word?)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're trying to deter people from creating them - as there's no guarantee that it'll be something Lagoon always supports - ad they introduce a lot of complexity that is better resolved elsewhere. Rather than telling people how to create them, I wanted to explain how they work when inherited (eg via gitlab sync)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there's no guarantee that it'll be something Lagoon always supports - ad they introduce a lot of complexity that is better resolved elsewhere

Should we say that directly in this section then?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the title of the section to hopefully be clearer, and also enhanced the warning on the page. Let me know if that is any better?


Consider this group structure:

``` mermaid
---
title: Subgroup permissions example
---
erDiagram
CompanyGroup ||--o{ DivisionGroup : child
DivisionGroup ||--o{ TeamGroup : child
```

If a User has `maintainer` role in the top level `CompanyGroup`, then they will also have `maintainer` level access to projects which are in the `TeamGroup`.

Note that this relationship is indirect: the Project is not in the same group as the User, but because the Project is in a _subgroup_ of the User's group, the User has `maintainer` permissions on the Project.
6 changes: 5 additions & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,11 @@ markdown_extensions:
- pymdownx.tilde
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.superfences
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- tables
- toc:
permalink: "#"
Expand Down