From b2b18812025b6628988c0feb6c59a2b6413021be Mon Sep 17 00:00:00 2001 From: Scott Leggett Date: Fri, 11 Oct 2024 09:30:59 +0800 Subject: [PATCH 1/3] chore: update group docs to describe subgroups and inherited roles --- .../concepts-basics/building-blocks/groups.md | 37 ++++++++++++++++++- mkdocs.yml | 6 ++- 2 files changed, 40 insertions(+), 3 deletions(-) diff --git a/docs/concepts-basics/building-blocks/groups.md b/docs/concepts-basics/building-blocks/groups.md index 69aa5fddb8..172a4d437e 100644 --- a/docs/concepts-basics/building-blocks/groups.md +++ b/docs/concepts-basics/building-blocks/groups.md @@ -1,5 +1,38 @@ # 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. + However, they can be useful in some situations. + +Groups can be nested to an arbitrary depth. +Subgroups are groups which are a child of another group. + +A user's role in an ancestor group is inherited by descendant groups. + +## Subgroups example + +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. diff --git a/mkdocs.yml b/mkdocs.yml index 935e5c75fa..5ffa80535e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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: "#" From c583b155340d8cbb32fa6a3d660d01c722d58977 Mon Sep 17 00:00:00 2001 From: Scott Leggett Date: Tue, 15 Oct 2024 11:17:08 +0800 Subject: [PATCH 2/3] chore: add note about how subgroups can be created --- docs/concepts-basics/building-blocks/groups.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/concepts-basics/building-blocks/groups.md b/docs/concepts-basics/building-blocks/groups.md index 172a4d437e..0770dc6a52 100644 --- a/docs/concepts-basics/building-blocks/groups.md +++ b/docs/concepts-basics/building-blocks/groups.md @@ -13,7 +13,10 @@ If you need to change the quota, please contact {{ defaults.helpstring }}. !!! warning Subgroups and not commonly used in Lagoon, and you probably don't need them. - However, they can be useful in some situations. + 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. From ef4c6535c22cfe903de48b1c9963bf9be5884bdf Mon Sep 17 00:00:00 2001 From: Scott Leggett Date: Tue, 15 Oct 2024 14:32:01 +0800 Subject: [PATCH 3/3] chore: update based on review * fix typo * clean up diagram * enhance warning --- docs/concepts-basics/building-blocks/groups.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/concepts-basics/building-blocks/groups.md b/docs/concepts-basics/building-blocks/groups.md index 0770dc6a52..2f11548b7e 100644 --- a/docs/concepts-basics/building-blocks/groups.md +++ b/docs/concepts-basics/building-blocks/groups.md @@ -11,9 +11,11 @@ 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. - However, they can be useful in some rare situations. +!!! danger + Subgroups are not commonly used in Lagoon. + Unless you are a Lagoon developer, and know exactly what you are doing, you shouldn't use them. + + There is also no guarantee that subgroups will be something Lagoon supports in future, since their complexity is out of proportion to the functionality they provide. !!! note Subgroups are not exposed by the Lagoon UI or Lagoon CLI, but can be created through the Lagoon GraphQL API. @@ -23,14 +25,11 @@ Subgroups are groups which are a child of another group. A user's role in an ancestor group is inherited by descendant groups. -## Subgroups example +## Subgroup permission inheritance example Consider this group structure: -``` mermaid ---- -title: Subgroup permissions example ---- +```mermaid erDiagram CompanyGroup ||--o{ DivisionGroup : child DivisionGroup ||--o{ TeamGroup : child