docs: update how-tos with roles

docs-rtd/.custom_wordlist.txt

@@ -2,6 +2,7 @@ CIDRs
 CPUs
 declaratively
 Hashicorp
+jaas
 JAAS
 JIMM
 juju
@@ -17,3 +18,5 @@ SREs
 TLS
 Unexpose
 unexpose
+uuid
+UUID

docs-rtd/howto/index.md

@@ -22,6 +22,7 @@ manage-ssh-keys
 manage-users
 manage-groups
 manage-service-accounts
+manage-roles
 manage-secrets
 ```
 

docs-rtd/howto/manage-clouds.md

@@ -33,15 +33,16 @@ resource "juju_model" "my-model" {
 At present the Terraform Provider for Juju supports cloud access management only for clouds added to a Juju controller added to JIMM.
 ```
 
-When using Juju with JAAS, to grant one or more users, groups, and/or service accounts access to a JAAS-known cloud, in your Terraform plan add a resource type `juju_jaas_access_cloud`, specifying the cloud name, the JAAS cloud access level, and the desired list of users, groups, and/or service accounts. For example:
+When using Juju with JAAS, to grant one or more users, service accounts, roles, and/or groups access to a JAAS-known cloud, in your Terraform plan add a resource type `juju_jaas_access_cloud`, specifying the cloud name, the JAAS cloud access level, and the desired list of users, service accounts, roles, and/or groups. For example:
 
 ```terraform
 resource "juju_jaas_access_cloud" "development" {
   cloud_name       = "aws"
   access           = "can_addmodel"
   users            = ["[email protected]"]
-  groups           = [juju_jaas_group.development.uuid]
   service_accounts = ["Client-ID-1", "Client-ID-2"]
+  roles            = [juju_jaas_role.development.uuid]
+  groups           = [juju_jaas_group.development.uuid]
 }
 ```
 

docs-rtd/howto/manage-controllers.md

@@ -10,14 +10,15 @@
 At present the Terraform Provider for Juju supports controller access management only for Juju controllers added to JIMM.
 ```
 
-When using Juju with JAAS, to grant one or more users, groups, and/or service accounts access to a Juju controller added to JIMM, in your Terraform plan add a resource type `juju_jaas_access_controller`, specifying the model UUID, the JAAS controller access level, and the desired list of users, groups, and/or service accounts. For example:
+When using Juju with JAAS, to grant one or more users, service accounts, roles, and/or groups access to a Juju controller added to JIMM, in your Terraform plan add a resource type `juju_jaas_access_controller`, specifying the model UUID, the JAAS controller access level, and the desired list of users, service accounts, roles, and/or groups. For example:
 
 ```terraform
 resource "juju_jaas_access_controller" "development" {
   access           = "administrator"
   users            = ["[email protected]"]
-  groups           = [juju_jaas_group.development.uuid]
   service_accounts = ["Client-ID-1", "Client-ID-2"]
+  roles            = [juju_jaas_role.development.uuid]
+  groups           = [juju_jaas_group.development.uuid]
 }
 ```
 

docs-rtd/howto/manage-groups.md

@@ -33,7 +33,7 @@ resource "juju_jaas_group" "development" {
 (manage-access-to-a-group)=
 ## Manage access to a group
 
-When using Juju with JAAS, to grant one or more users, groups, and/or service accounts access to a group, in your Terraform plan add a resource type `juju_jaas_access_group`, specifying the group ID, the JAAS group access level, and the list of desired users, groups, and/or service accounts. For example:
+When using Juju with JAAS, to grant one or more users, service accounts, roles, and/or groups access to a group, in your Terraform plan add a resource type `juju_jaas_access_group`, specifying the group ID, the JAAS group access level, and the list of desired users, service accounts, roles, and/or groups. For example:
 
 
 ```{note}
@@ -45,13 +45,14 @@ resource "juju_jaas_access_group" "development" {
   group_id         = juju_jaas_group.target-group.uuid
   access           = "member"
   users            = ["[email protected]"]
-  groups           = [juju_jaas_group.development.uuid]
   service_accounts = ["Client-ID-1", "Client-ID-2"]
+  roles            = [juju_jaas_role.development.uuid]
+  groups           = [juju_jaas_group.development.uuid]
 }
 ```
 
 > See more: [`juju_jaas_access_group`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/jaas_access_group), [JAAS | Group access levels](https://canonical-jaas-documentation.readthedocs-hosted.com/en/latest/reference/authorisation_model/#group)
 
-## Manage a group's access to a controller, cloud, model, offer, or group
+## Manage a group's access to a controller, cloud, model, offer, role, or group
 
-> 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-group`
+> 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`

docs-rtd/howto/manage-models.md

@@ -89,7 +89,7 @@ resource "juju_model" "this" {
 (manage-access-to-a-model)=
 ## Manage access to a model
 
-Your model access management options depend on whether the controller you are applying the Terraform plan to is a regular Juju controller or rather a Juju controller added to JIMM -- for the former you can grant access only to a user, but for the latter you can grant access to a user, a group, or a service account.
+Your model access management options depend on whether the controller you are applying the Terraform plan to is a regular Juju controller or rather a Juju controller added to JIMM -- for the former you can grant access only to a user, but for the latter you can grant access to a user, a service account, a role, or a group.
 
 
 ### For a regular Juju controller
@@ -107,15 +107,16 @@ resource "juju_access_model" "this" {
 
 
 ### For a Juju controller added to JIMM
-To grant one or more users, groups, and/or service accounts access to a model, in your Terraform plan add a resource type `juju_jaas_access_model`, specifying the model UUID, the JAAS model access level, and the desired list of users, groups, and/or service accounts. For example:
+To grant one or more users, service accounts, roles, and/or groups access to a model, in your Terraform plan add a resource type `juju_jaas_access_model`, specifying the model UUID, the JAAS model access level, and the desired list of users, service accounts, roles, and/or groups. For example:
 
 ```terraform
 resource "juju_jaas_access_model" "development" {
   model_uuid       = juju_model.development.uuid
   access           = "administrator"
   users            = ["[email protected]"]
-  groups           = [juju_jaas_group.development.uuid]
   service_accounts = ["Client-ID-1", "Client-ID-2"]
+  roles            = [juju_jaas_role.development.uuid]
+  groups           = [juju_jaas_group.development.uuid]
 }
 
 ```

docs-rtd/howto/manage-offers.md

@@ -93,7 +93,7 @@ resource "juju_integration" "this" {
 (manage-access-to-an-offer)=
 ## Manage access to an offer
 
-Your offer access management options depend on whether the controller you are applying the Terraform plan to is a regular Juju controller or rather a a Juju controller connected to JIMM -- for the former you can grant access only to a user, but for the latter you can grant access to a user, a group, or a service account.
+Your offer access management options depend on whether the controller you are applying the Terraform plan to is a regular Juju controller or rather a a Juju controller connected to JIMM -- for the former you can grant access only to a user, but for the latter you can grant access to a user, a service account, a role, or a group.
 
 
 ### For a regular Juju controller
@@ -110,15 +110,16 @@ resource "juju_access_offer" "this" {
 
 
 ### For a Juju controller added to JIMM
-To grant one or more users, groups, and/or service accounts access to a model, in your Terraform plan add a resource type `juju_jaas_access_offer`, specifying the offer URL, the access level, and the desired list desired users, groups, and/or service accounts. For example:
+To grant one or more users, service accounts, roles, and/or groups access to a model, in your Terraform plan add a resource type `juju_jaas_access_offer`, specifying the offer URL, the JAAS offer access level, and the desired list desired users, service accounts, roles, and/or groups. For example:
 
 ```terraform
 resource "juju_jaas_access_offer" "development" {
   offer_url        = juju_offer.myoffer.url
   access           = "consumer"
   users            = ["[email protected]"]
-  groups           = [juju_jaas_group.development.uuid]
   service_accounts = ["Client-ID-1", "Client-ID-2"]
+  roles            = [juju_jaas_role.development.uuid]
+  groups           = [juju_jaas_group.development.uuid]
 }
 ```
 

docs-rtd/howto/manage-roles.md

@@ -0,0 +1,62 @@
+(manage-groups)=
+# Manage groups
+
+```{note}
+In the Juju ecosystem, roles are supported only when using [JAAS](https://canonical-jaas-documentation.readthedocs-hosted.com/en/latest/).
+```
+
+(reference-an-externally-managed-role)=
+## Reference an externally managed role
+
+To reference a role you've created outside of the current Terraform plan, in your Terraform plan add a data source of the `juju_jaas_role` type, specifying the name of the role. Optionally, you may also output the role's UUID so you can later reference it in other resources. For example:
+
+```terraform
+data "juju_jaas_role" "test" {
+  name = "role-0"
+}
+output "role_uuid" {
+  value = data.juju_jaas_role.test.uuid
+}
+```
+
+> See more: [`juju_jaas_role` (data source)](https://registry.terraform.io/providers/juju/juju/latest/docs/data-sources/jaas_role)
+
+(add-a-role)=
+## Add a role
+
+To add a role, in your Terraform plan create a resource of the `juju_jaas_role` type, specifying its name. For example:
+
+```terraform
+resource "juju_jaas_role" "development" {
+  name = "devops-team"
+}
+```
+
+> See more: [`juju_jaas_role` (resource)](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/jaas_role)
+
+(manage-access-to-a-role)=
+## Manage access to a role
+
+When using Juju with JAAS, to grant one or more users, service accounts, and/or groups  access to a role, in your Terraform plan add a resource type `juju_jaas_access_role`, specifying the role, the JAAS role access level, and the list of desired users, service accounts, and/or groups. For example:
+
+
+```{note}
+At present, the only valid JAAS role access level is `assignee`, so granting an entity access to a role effectively means giving them a particular role.
+```
+
+
+```terraform
+resource "juju_jaas_access_role" "development" {
+  role_id          = juju_jaas_role.target-role.uuid
+  roles            = [juju_jaas_role.development.uuid]
+  access           = "assignee"
+  users            = ["[email protected]"]
+  service_accounts = ["Client-ID-1", "Client-ID-2"]
+}
+```
+
+> See more: [`juju_jaas_access_role`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/jaas_access_role), [JAAS | Role access levels](https://canonical-jaas-documentation.readthedocs-hosted.com/en/latest/reference/authorisation_model/#role)
+
+## Manage a role's access to a controller, cloud, model, offer, or group
+
+> 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-group`

docs-rtd/howto/manage-service-accounts.md

@@ -9,19 +9,20 @@ In the Juju ecosystem, service accounts are supported only when using [JAAS](htt
 (manage-access-to-a-service account)=
 ## Manage access to a service account
 
-When using Juju with JAAS, to grant a user, a group, or a service account access to a Juju controller connected to JIMM, in your Terraform plan add a resource type `juju_jaas_access_controller`, specifying the model UUID, the JAAS controller access level, and the list of desired users, groups, and/or service accounts. For example:
+When using Juju with JAAS, to grant a one or more users, service accounts, roles, and/or groups access to a Juju controller connected to JIMM, in your Terraform plan add a resource type `juju_jaas_access_controller`, specifying the model UUID, the JAAS controller access level, and the list of desired users, service accounts, roles, and/or groups. For example:
 
 ```terraform
 resource "juju_jaas_access_controller" "development" {
   access           = "administrator"
   users            = ["[email protected]"]
-  groups           = [juju_jaas_group.development.uuid]
   service_accounts = ["Client-ID-1", "Client-ID-2"]
+  roles            = [juju_jaas_role.development.uuid]
+  groups           = [juju_jaas_group.development.uuid]
 }
 ```
 
 > See more: [`juju_jaas_access_service_account`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/jaas_access_service_account), [JAAS | Service account access levels](https://canonical-jaas-documentation.readthedocs-hosted.com/en/latest/reference/authorisation_model/#service-account)
 
-## Manage a service account's access to a controller, cloud, model, offer, or group
+## Manage a service account's access to a controller, cloud, model, offer, role, or group
 
-> 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-group`
+> 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`

docs-rtd/howto/manage-terraform-provider-juju.md

@@ -3,7 +3,7 @@
 
 ## Install `terraform-provider-juju`
 
-To install `terraform-provider-juju` on Linux, macOS, or Windows, you need to install the `terraform` CLI. 
+To install `terraform-provider-juju` on Linux, macOS, or Windows, you need to install the `terraform` CLI.
 
 > See more: [Hashicorp | Install Terraform](https://developer.hashicorp.com/terraform/install)
 
@@ -62,7 +62,7 @@ Once you've installed the `terraform` CLI, to start using it:
 
     ```terraform
     provider "juju" {}
-    ``` 
+    ```
 
     Then, in a terminal, export the controller environment variables with your controller's values. For example:
 

docs-rtd/howto/manage-users.md

@@ -18,9 +18,9 @@ resource "juju_user" "alex" {
 > See more: [`juju_user` (resource)](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/user)
 
 
-## Manage a user's access to a controller, cloud, model, offer, or group
+## Manage a user's access to a controller, cloud, model, offer, role, or group
 
-> 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-group`
+> 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`
 
 ## Manager a user's login details
 
@@ -41,8 +41,3 @@ resource "juju_user" "alex" {
 To remove a user, in your Terraform plan remove its resource definition.
 
 > See more: [`juju_user` (resource)](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/user)
-
-
-<br>
-
-> <small>**Contributors:** @cderici, @hmlanigan, @pedroleaoc, @pmatulis, @timclicks, @tmihoc </small>