docs: update language from access level to relation

tmihoc · tmihoc · commit c7c542c25e82 · 2025-03-18T17:23:36.000+01:00
diff --git a/howto/manage-clouds.md b/howto/manage-clouds.md
@@ -2,13 +2,7 @@
 # Manage clouds
 > See first: {ref}`cloud`
 
-(manage-access-to-a-cloud)=
-## Manage access to a cloud
+(manage-an-entitys-relation-to-a-cloud)=
+## Manage an entity's relation to a cloud
 
-**Grant access to a cloud.** Given an entity A and a cloud, to grant A access to the cloud, add a relation between A and the cloud, specifying the desired access level.
-
-> See more: {ref}`add-a-relation`
-
-**Revoke access to a cloud.** Given an entity A and a cloud, to revoke A's access to the cloud, remove the relation that grants that access.
-
-> See more: {ref}`remove-a-relation`
+See {ref}`manage-relations`.
diff --git a/howto/manage-groups.md b/howto/manage-groups.md
@@ -53,6 +53,11 @@ jimmctl auth group list [options]
 
 > See more: {ref}`jimmctl auth group list <summary-6>`
 
+(manage-an-entitys-relation-to-a-group)=
+## Manage an entity's relation to a group
+
+See {ref}`manage-relations`.
+
 
 (manage-access-to-a-group)=
 ## Manage access to a group
diff --git a/howto/manage-juju-controllers.md b/howto/manage-juju-controllers.md
@@ -117,14 +117,8 @@ jimmctl controller-info workload-lxd ~/snap/jimmctl/common/lxd-controller-info.y
 jimmctl add-controller ~/snap/jimmctl/common/lxd-controller-info.yaml
 ```
 
-(manage-access-to-a-juju-controller)=
-## Manage access to a Juju controller
+(manage-an-entitys-relation-to-a-juju-controller)=
+## Manage an entity's relation to a Juju controller
 
-**Grant access to a Juju controller.** Given an entity A and a controller, to grant A access to the controller, add a relation between A and the controller, specifying the desired access level.
-
-> See more: {ref}`add-a-relation`
-
-**Revoke access to a Juju controller.** Given an entity A and a controller, to revoke A's access to the controller, remove the relation that grants that access.
-
-> See more: {ref}`remove-a-relation`
+See {ref}`manage-relations`.
 
diff --git a/howto/manage-models.md b/howto/manage-models.md
@@ -158,13 +158,7 @@ To inspect the reason for failure, consult the output from `juju debug-log` and
 
 
 
-(manage-access-to-a-model)=
-## Manage access to a model
+(manage-an-entitys-relation-to-a-model)=
+## Manage an entity's relation to a model
 
-**Grant access to a model.** Given an entity A and a model, to grant A access to the model, add a relation between A and the model, specifying the desired access level.
-
-> See more: {ref}`add-a-relation`
-
-**Revoke access to a model.** Given an entity A and a model, to revoke A's access to the model, remove the relation that grants that access.
-
-> See more: {ref}`remove-a-relation`
+See {ref}`manage-relations`.
diff --git a/howto/manage-offers.md b/howto/manage-offers.md
@@ -1,13 +1,7 @@
 (manage-offers)=
 # Manage offers
 
-(manage-access-to-an offer)=
-## Manage access to an offer
+(manage-an-entitys-relation-to-an-offer)=
+## Manage an entity's relation to an offer
 
-**Grant access to an offer.** Given an entity A and an offer, to grant A access to the offer, add a relation between A and the offer, specifying the desired access level.
-
-> See more: {ref}`add-a-relation`
-
-**Revoke access to an offer.** Given an entity A and an offer, to revoke A's access to the offer, remove the relation that grants that access.
-
-> See more: {ref}`remove-a-relation`
+See {ref}`manage-relations`.
diff --git a/howto/manage-relations.md b/howto/manage-relations.md
@@ -12,9 +12,9 @@ jimmctl auth relation add user-alice@canonical.com member group-mygroup
 ```
 
 > See more:
-> - {ref}`tag`
 > - {ref}`jimmctl auth relation add <summary-10>`
-> - {ref}`controller-access-levels`, {ref}`cloud-access-levels`, {ref}`model-access-levels`, {ref}`offer-access-levels`, {ref}`service-account-access-levels`, {ref}`role-access-levels`, {ref}`group-access-levels`
+> - {ref}`controller-tag`, {ref}`cloud-tag`, {ref}`model-tag`, {ref}`offer-tag`, {ref}`user-tag`, {ref}`service-account-tag`, {ref}`role-tag`, {ref}`group-tag`
+> - {ref}`list-of-controller-relations`, {ref}`list-of-cloud-relations`, {ref}`list-of-model-relations`, {ref}`list-of-offer-relations`, {ref}`list-of-service-account-relations`, {ref}`list-of-role-relations`, {ref}`list-of-group-relations`
 
 
 (verify-a-relation)=
diff --git a/howto/manage-roles.md b/howto/manage-roles.md
@@ -49,22 +49,15 @@ jimmctl auth role list [options]
 
 > See more: {ref}`jimmctl auth role list <summary-16>`
 
+(manage-an-entitys-relation-to-a-role)=
+## Manage an entity's relation to a role
 
-(manage-access-to-a-role)=
-## Manage access to a role
+See {ref}`manage-relations`.
 
-**Grant access to a role.** Given an entity A and a role, to grant A access to the role, add a relation between A and the role, specifying the desired access level.
+(manage-a-roles-relation-to-an-entity)=
+## Manage a role's relation to an entity
 
-> See more: {ref}`add-a-relation`
-
-**Revoke access to a role.** Given an entity A and a role, to revoke A's access to the role, remove the relation that grants that access.
-
-> See more: {ref}`remove-a-relation`
-
-(manage-a-roles-access)=
-## Manage a role’s access to a controller, cloud, model, or offer
-
-> See more: {ref}`manage-access-to-a-controller`, {ref}`manage-access-to-a-cloud`, {ref}`manage-access-to-a-model`, {ref}`manage-access-to-an-offer`
+See {ref}`manage-relations`.
 
 (rename-a-role)=
 ## Rename a role
diff --git a/howto/manage-service-accounts.md b/howto/manage-service-accounts.md
@@ -2,7 +2,7 @@
 # Manage service accounts
 > See also: {ref}`service account`
 
-(manage-a-service-accounts-access)=
-## Manage a service account’s access to a controller, cloud, model, offer, role, or group
+(manage-a-service-accounts-relation-to-an-entity)=
+## Manage a service account's relation to an entity
 
-> See more: {ref}`manage-access-to-a-controller`, {ref}`manage-access-to-a-cloud`, {ref}`manage-access-to-a-model`, {ref}`manage-access-to-an-offer`, {ref}`manage-access-to-a-role`, {ref}`manage-access-to-a-group`
+See {ref}`manage-relations`.
diff --git a/howto/manage-users.md b/howto/manage-users.md
@@ -2,7 +2,7 @@
 # Manage users
 > See first: {ref}`user`
 
-(manage-a-users-access)=
-## Manage a user’s access to a controller, cloud, model, offer, service-account, role, or group
+(manage-a-users-relation-to-an-entity)=
+## Manage a user's relation to an entity
 
-> See more: {ref}`manage-access-to-a-controller`, {ref}`manage-access-to-a-cloud`, {ref}`manage-access-to-a-model`, {ref}`manage-access-to-an-offer`, {ref}`manage-access-to-a-service-account`, {ref}`manage-access-to-a-role`, {ref}`manage-access-to-a-group`
+See {ref}`manage-relations`.
diff --git a/reference/cloud.md b/reference/cloud.md
@@ -13,15 +13,16 @@ A cloud tag has the following format:
 cloud-<cloud name>
 ```
 
-(cloud-access-levels)=
-## Cloud access levels
+(list-of-cloud-relations)=
+## List of cloud relations
+> See first: {ref}`relation`
 
-(cloud-access-levels-administrator)=
+(cloud-relation-administrator)=
 ### `administrator`
 
 Abilities: Can do anything that it is possible to do at the level of a cloud.
 
-(cloud-access-levels-can-addmodel)=
+(cloud-relation-can-addmodel)=
 ### `can_addmodel`
 
 Abilities: Can add a model and grant another user model-level permissions.
diff --git a/reference/controller.md b/reference/controller.md
@@ -14,15 +14,16 @@ A controller tag has the following format:
 controller-<controller name>
 ```
 
-(controller-access-levels)=
-## Controller access levels
+(list-of-controller-relations)=
+## List of controller relations
+> See first: {ref}`relation`
 
-(controller-access-levels-administrator)=
+(controller-relation-administrator)=
 ### `administrator`
 
 Abilities: Can do anything that it is possible to do at the level of a controller. This grants permissions to all resources that inherit from controller access.
 
-(controller-access-levels-audit-log-viewer)=
+(controller-relation-audit-log-viewer)=
 ### `audit_log_viewer`
 
 Abilities: Can read audit logs.
diff --git a/reference/group.md b/reference/group.md
@@ -18,10 +18,11 @@ group-<group id>
 where `group id` represents the unique identifier of the group.
 
 
-(group-access-levels)=
-## Group access levels
+(list-of-group-relations)=
+## Group relations
+> See first: {ref}`relation`
 
-(group-access-levels-member)=
+(group-relation-member)=
 ### `member`
 
 Abilities: Shares the group's access level to Juju resources and JIMM logs.
diff --git a/reference/model.md b/reference/model.md
@@ -15,20 +15,21 @@ model-<controller name>/<model name>
 where `<controller name>` specifies name of the controller on which the model
 is running and `<model name>` specifies the name of the model.
 
-(model-access-levels)=
-## Model access levels
+(list-of-model-relations)=
+## List of model relations
+> See first: {ref}`relation`
 
-(model-access-levels-reader)=
+(model-relation-reader)=
 ### `reader`
 
 Abilities: Can view the content of a model without changing it. Can use any of the read commands.
 
-(model-access-levels-writer)=
+(model-relation-writer)=
 ### `writer`
 
 Abilities: Can deploy and manage applications on the model.
 
-(model-access-levels-administrator)=
+(model-relation-administrator)=
 ### `administrator`
 
 Abilities: Can do anything that it is possible to do at the level of a model.This grants permissions to all resources that inherit from model access.
diff --git a/reference/offer.md b/reference/offer.md
@@ -19,20 +19,21 @@ is running, `<model name>` specifies name of the model in which the application
 offer was created and `<offer name>` specifies the name of the application offer.
 
 
-(offer-access-levels)=
-## Offer access levels
+(list-of-offer-relations)=
+## List of offer relations
+> See first: {ref}`relation`
 
-(offer-access-levels-administrator)=
+(offer-relation-administrator)=
 ### `administrator`
 
 Abilities: Can do anything that it is possible to do at the level of an offer.
 
-(offer-access-levels-consumer)=
+(offer-relation-consumer)=
 ### `consumer`
 
 Abilities: Can relate an application to the offer.
 
-(offer-access-levels-reader)=
+(offer-relation-reader)=
 ### `reader`
 
 Abilities: Can view offers during a search with `juju find-offers`.
diff --git a/reference/relation.md b/reference/relation.md
@@ -2,7 +2,15 @@
 # Relation
 > See also: {ref}`manage-relations`
 
-In JAAS, like in [OpenFGA](https://openfga.dev/docs/concepts#what-is-a-relation) and unlike in{external+juju:ref}`Juju <relation>`, a relation is about Relation Based Access Control (**ReBAC**) and describes the relation between two entities.
+In JAAS, like in [OpenFGA](https://openfga.dev/docs/concepts#what-is-a-relation), a relation is about Relation Based Access Control (**ReBAC**) and describes the relationship between two entities.
 
 
-A relation is always associated with an {ref}`access level <access>`.
+```{important}
+**Juju relations vs. JAAS relations:**
+
+JAAS relations have nothing to the with {external+juju:ref}`Juju relations <relation>`, which refer to the relationship, or rather integration, of two charmed applications.
+
+JAAS relations are currently similar to {external+juju:ref}`Juju access levels <user-access-levels>` -- they're both about permissions. The difference is that the relation paradigm is much broader; the list of relations is anticipated to become a superset of Juju access levels; and, while Juju access levels are always about a user's permissions on a controller, cloud, model, or offer, JAAS relations encompass many more entities on both sides, e.g., groups, roles, and service accounts.
+```
+
+> See more: {ref}`list-of-controller-relations`, {ref}`list-of-cloud-relations`, {ref}`list-of-model-relations`, {ref}`list-of-offer-relations`, {ref}`list-of-service-account-relations`, {ref}`list-of-role-relations`, {ref}`list-of-group-relations`
diff --git a/reference/role.md b/reference/role.md
@@ -19,10 +19,11 @@ role-<role id>
 where `role id` represents the unique identifier of the role.
 
 
-(role-access-levels)=
-## Role access levels
+(list-of-role-relations)=
+## List of role relations
+> See first: {ref}`relation`
 
-(role-access-levels-assignee)=
+(role-relation-assignee)=
 ### `assignee`
 
 Abilities: Shares the role's access level to Juju resources and JIMM logs.
diff --git a/reference/service-account.md b/reference/service-account.md
@@ -24,10 +24,12 @@ A `serviceaccount-<identifier>` type tag is only useful for providing permission
 In all other cases treat service accounts as users and use a {ref}`user tag <user-tag>` to grant them access to resources.
 ```
 
-(service-account-access-levels)=
-## Service account access levels
+(list-of-service-account-relations)=
+## List of service account relations
+> See first: {ref}`relation`
 
-(service-account-access-levels-administrator)=
+
+(service-account-relation-administrator)=
 ### `administrator`
 
 Abilities: Can do anything that it is possible to do at the level of a service account. Used to manage the credentials of a service account.
