docs: add how-tos for clouds, remove contributors, etc.

docs-rtd/howto/manage-applications.md

@@ -5,7 +5,7 @@
 
 ## Reference an externally managed application
 
-To reference an application that you've already deployed with Juju tools other than the Terraform Provider for Juju, in your Terraform plan add a data source of the `juju_application` type, specifying the name of the application and of the model it is deployed to. For example:
+To reference an application that you've deployed outside of the current Terraform plan, in your Terraform plan add a data source of the `juju_application` type, specifying the name of the application and of the model it is deployed to. For example:
 
 ```terraform
 data "juju_application" "my-application" {
@@ -32,7 +32,7 @@ TBA
 ## Trust an application with a credential
 
 
-Some applications may require access to the backing cloud in order to fulfil their purpose (e.g., storage-related tasks). In such cases, the remote credential associated with the current model would need to be shared with the application. When the Juju administrator allows this to occur the application is said to be *trusted*. 
+Some applications may require access to the backing cloud in order to fulfil their purpose (e.g., storage-related tasks). In such cases, the remote credential associated with the current model would need to be shared with the application. When the Juju administrator allows this to occur the application is said to be *trusted*.
 
 To trust an application with a credential, in the `juju_application` resource definition, add a `trust` attribute and set it to `true`:
 
@@ -66,8 +66,8 @@ resource "juju_application" "this" {
   }
 
   config = {
-    redirect-map = "https://demo"      
-   }    
+    redirect-map = "https://demo"
+   }
 }
 ```
 > See more: [`juju_application` (resource)](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application#schema)
@@ -81,7 +81,7 @@ resource "juju_application" "this" {
 ### Scale an application vertically
 
 To scale an application vertically, set constraints for the resources that the application's units will be deployed on.
- 
+
 > See more: {ref}`manage-constraints-for-an-application`
 
 (scale-an-application-horizontally)=
@@ -95,7 +95,7 @@ To scale an application horizontally, control the number of units.
 ## Make an application highly available
 > See also: [`juju` | High availability (HA)](https://juju.is/docs/juju/high-availability)
 
-1. Find out if the charm delivering the application supports high availability natively or not. If the latter, find out what you need to do. This could mean integrating with a load balancing reverse proxy, configuring storage etc. 
+1. Find out if the charm delivering the application supports high availability natively or not. If the latter, find out what you need to do. This could mean integrating with a load balancing reverse proxy, configuring storage etc.
 
 > See more: [Charmhub > `<your charm of interest>`](https://charmhub.io/)
 
@@ -138,8 +138,8 @@ resource "juju_application" "this" {
 
   expose = {
     endpoints = "..., ..."
-    spaces = 
-    cidrs = 
+    spaces =
+    cidrs =
   }
 }
 ```
@@ -210,7 +210,7 @@ resource "juju_application" "application_three" {
 
 ## Upgrade an application
 
-To upgrade an application, update its charm. 
+To upgrade an application, update its charm.
 
 > See more: {ref}`update-a-charm`
 
@@ -219,7 +219,6 @@ To upgrade an application, update its charm.
 
 > See also: [`juju` | Removing things](https://juju.is/docs/juju/removing-things)
 
-
 To remove an application, remove its resource definition from your Terraform plan.
 
 > See more: [`juju_application` (resource)](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application#schema)

docs-rtd/howto/manage-charm-resources.md

@@ -1,7 +1,7 @@
 (manage-charm-resources)=
 # Manage charm resources
 
-> See also: [`juju` | Resource (charm)](https://juju.is/docs/juju/charm-resource)
+> See also: [Juju | Resource (charm)](https://juju.is/docs/juju/charm-resource)
 
 When you deploy / update an application from a charm, that automatically deploys / updates any charm resources, using the defaults specified by the charm author. However, you can also specify resources manually (e.g., to try a resource released only to `edge` or to specify a non-Charmhub resource). This document shows you how.
 

docs-rtd/howto/manage-clouds.md

@@ -8,7 +8,22 @@
 (add-a-kubernetes-cloud)=
 ## Add a Kubernetes cloud
 
-TBA
+To add a Kubernetes cloud to the controller that your Terraform plan is connected to, in your Terraform plan add a resource of the `juju_kubernetes_cloud` type, specifying a name and the path to the kubeconfig file. The example below does this and also creates a model associated with the new cloud:
+
+```terraform
+resource "juju_kubernetes_cloud" "my-k8s-cloud" {
+  name              = "my-k8s-cloud"
+  kubernetes_config = file("<path-to-my-kubennetes-cloud-config>.yaml")
+}
+
+resource "juju_model" "my-model" {
+  name       = "my-model"
+  credential = juju_kubernetes_cloud.my-k8s-cloud.credential
+  cloud {
+    name = juju_kubernetes_cloud.my-k8s-cloud.name
+  }
+}
+```
 
 > See more: [`juju_kubernetes_cloud`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/kubernetes_cloud)
 

docs-rtd/howto/manage-credentials.md

@@ -1,7 +1,7 @@
 (manage-credentials)=
 # Manage credentials
 
-> See also: [Credential](https://juju.is/docs/juju/credential)
+> See also: [Juju | Credential](https://juju.is/docs/juju/credential)
 
 
 ## Define a credential

docs-rtd/howto/manage-groups.md

@@ -5,26 +5,22 @@
 In the Juju ecosystem, groups are supported only when using [JAAS](https://canonical-jaas-documentation.readthedocs-hosted.com/en/latest/).
 ```
 
-## ## Reference an externally managed group
+## Reference an externally managed group
 
 To reference a group you've created with Juju tools other than the Terraform Provider for Juju, in your Terraform plan add a data source of the `juju_jaas_group` type, specifying the name of the group. For example:
 
 ```terraform
 data "juju_jaas_group" "test" {
   name = "group-0"
 }
-
-output "group_uuid" {
-  value = data.juju_jaas_group.test.uuid
-}
 ```
 
 > See more: [`juju_jaas_group` (data source)](https://registry.terraform.io/providers/juju/juju/latest/docs/data-sources/jaas_group)
 
 
 ## Add a group
 
-To add a group, in your Terraform plan create a resource of the `juju_jaas_group` type, specifying, at the very least, a name. For example:
+To add a group, in your Terraform plan create a resource of the `juju_jaas_group` type, specifying its name. For example:
 
 ```terraform
 resource "juju_jaas_group" "development" {
@@ -39,6 +35,11 @@ resource "juju_jaas_group" "development" {
 
 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:
 
+
+```{note}
+At present, the only valid JAAS group access level is `member`, so granting an entity access to a group effectively means making them a member of the group.
+```
+
 ```terraform
 resource "juju_jaas_access_group" "development" {
   group_id         = juju_jaas_group.target-group.uuid
@@ -49,8 +50,8 @@ resource "juju_jaas_access_group" "development" {
 }
 ```
 
-```{note}
-At present, the only valid JAAS group access level is `member`.
-```
+> 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
 
-> 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)
+> 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-machines.md

@@ -7,7 +7,7 @@ An interactive pseudo-terminal (pty) is enabled by default. For the OpenSSH clie
 Remote commands can be run as expected. For example: `juju ssh 1 lsb_release -c`. For complex commands the recommended method is by way of the `run` command.
 -->
 
-> See also: [`juju` | Machine](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/machine/)
+> See also: [Juju | Machine](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/machine/)
 
 ## Reference an externally managed machine
 

docs-rtd/howto/manage-models.md

@@ -89,10 +89,11 @@ resource "juju_model" "this" {
 (manage-access-to-a-model)=
 ## Manage access to a model
 
-When using Juju alone, you can grant model access only to a user. When using Juju with JAAS, you can grant model 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 JAAS controller -- for a Juju controller you can grant access only to a user, but for a JAAS controller you can grant access to a user, a group, or a service account.
 
-### Using Juju alone
-When using Juju alone, to grant a user access to a model, in your Terraform plan add a `juju_access_model` resource, specifying the model, the Juju access level, and the user(s) to which you want to grant access. For example:
+
+### For a Juju controller
+To grant a user access to a model, in your Terraform plan add a `juju_access_model` resource, specifying the model, the Juju access level, and the user(s) to which you want to grant access. For example:
 
 ```terraform
 resource "juju_access_model" "this" {
@@ -105,8 +106,8 @@ resource "juju_access_model" "this" {
 > See more: [`juju_access_model`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/access_model), [Juju | Model access levels](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/user/#valid-access-levels-for-models)
 
 
-### Using Juju + JAAS
-When using Juju with JAAS, 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:
+### For a JAAS controller
+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:
 
 ```terraform
 resource "juju_jaas_access_model" "development" {

docs-rtd/howto/manage-offers.md

@@ -93,10 +93,11 @@ resource "juju_integration" "this" {
 (manage-access-to-an-offer)=
 ## Manage access to an offer
 
-When using Juju alone, you can grant offer access only to a user. When using Juju with JAAS, you can grant offer 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 JAAS controller -- for a Juju controller you can grant access only to a user, but for a JAAS controller you can grant access to a user, a group, or a service account.
 
-### Using Juju alone
-When using Juju alone, to grant a user access to an offer, in your Terraform plan add a `juju_access_offer` resource, specifying the offer URL and setting the Juju access level to the list of users you want to grant that level. For example:
+
+### For a Juju controller
+To grant a user access to an offer, in your Terraform plan add a `juju_access_offer` resource, specifying the offer URL and setting the Juju access level to the list of users you want to grant that level. For example:
 
 ```terraform
 resource "juju_access_offer" "this" {
@@ -108,8 +109,8 @@ resource "juju_access_offer" "this" {
 > See more: [`juju_access_offer`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/access_offer), [Juju | Offer access levels](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/user/#valid-access-levels-for-application-offers)
 
 
-### Using Juju + JAAS
-When using Juju with JAAS, 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:
+### For a JAAS controller
+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:
 
 ```terraform
 resource "juju_jaas_access_offer" "development" {

docs-rtd/howto/manage-relations.md

@@ -79,10 +79,3 @@ In a cross-model relation there is also an 'offering' model and a 'consuming' mo
 To remove a relation, in your Terraform plan, remove its resource definition.
 
 > See more: [`juju_integration` (resource)](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/integration)
-
-
-
-
-<br>
-
-> <small>**Contributors:** @amandahla, @aurelien-lourot , @cderici, @danieleprocida, @evilnick , @hmlanigan, @nottrobin , @pedroleaoc, @pmatulis, @tmihoc </small>

docs-rtd/howto/manage-secrets.md

@@ -1,7 +1,7 @@
 (manage-secrets)=
 # Manage secrets
 
-> See also: [`juju` | Secret](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/secret/)
+> See also: [Juju | Secret](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/secret/)
 
 Charms can use relations to share secrets, such as API keys, a database’s address, credentials and so on. This document demonstrates how to interact with them as a Juju user. 
 
@@ -45,7 +45,6 @@ resource "juju_secret" "my-secret" {
 
 ## Manage access to a secret
 
-
 Given a model that contains both your (user) secret and the application(s) that you want to grant access to, to grant the application(s) access to the secret, in your Terraform plan create a resource of the `juju_access_secret` type, specifying the model, the secret ID, and the application(s) that you wish to grant access to. For example:
 
 ```
@@ -78,6 +77,3 @@ To remove a secret, remove its resource definition from your Terraform plan.
 
 > See more: [`juju_secret` (resource)](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/secret)
 
-<br>
-
-> <small>Contributors: @anvial, @cderici, @kelvin.liu , @tmihoc, @tony-meyer , @wallyworld </small>

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

@@ -20,4 +20,8 @@ resource "juju_jaas_access_controller" "development" {
 }
 ```
 
-> 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)
+> 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
+
+> 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-ssh-keys.md

@@ -22,6 +22,3 @@ To remove an SSH key, remove its resource definition from your Terraform plan.
 
 > See more: [`juju_ssh_key` (resource)](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/ssh_key)
 
-<br>
-
-> <small>**Contributors:** @cderici, @hmlanigan, @tmihoc </small>

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

@@ -107,5 +107,3 @@ Once you've installed the `terraform` CLI, to start using it:
 To upgrade `terraform-provider-juju`, in your Terraform plan update the version constraint, then run `terraform init` with the `--upgrade` flag.
 
 > See more: Terraform [Version constraints](https://developer.hashicorp.com/terraform/language/providers/requirements#version-constraints), [`terraform init --upgrade`](https://developer.hashicorp.com/terraform/cli/commands/init#upgrade-1)
-
-> <small> **Contributors:** @cderici, @hmlanigan, @simonrichardson, @timclicks, @tmihoc</small>

docs-rtd/howto/manage-units.md

@@ -23,8 +23,3 @@ resource "juju_application" "this" {
 
 > See more: [`juju_application` (resource)](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application#schema)
 
-
-
-<br>
-
-> <small>**Contributors:** @cderici, @hmlanigan, @skourta, @tmihoc </small>

docs-rtd/howto/manage-users.md

@@ -18,11 +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 level
-> See also: [Juju | User access levels](https://juju.is/docs/juju/user-permissions)
+## Manage a user's access to a controller, cloud, model, offer, or group
 
-> See more: 
-> - 
+> 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`
 
 ## Manager a user's login details
 

docs-rtd/index.md

@@ -13,9 +13,9 @@ reference/index
 explanation/index
 -->
 
-The Terraform Provider for Juju (henceforth, `terraform-provider-juju`) is a [Terraform Provider](https://developer.hashicorp.com/terraform/language/providers) that extends [Terraform](https://developer.hashicorp.com/terraform) with [Juju](https://juju.is) functionality.
+The Terraform Provider for Juju (henceforth, `terraform-provider-juju`) is a [Terraform Provider](https://developer.hashicorp.com/terraform/language/providers) that extends [Terraform](https://developer.hashicorp.com/terraform) with [Juju](https://juju.is) and [JAAS](https://jaas.ai/) functionality.
 
-When you're putting together your Terraform plan, if you specify `juju` as the provider, you can connect to a pre-existing Juju controller (created with the [`juju` CLI](https://juju.is/docs/juju/juju-client)) and then go ahead and use it to do Juju things -- easy deploy, configure, integrate, scale, etc., applications on any Juju-supported cloud (Kubernetes or otherwise) using [charms](https://juju.is/docs/juju/charmed-operator).
+When you're putting together your Terraform plan, if you specify `juju` as the provider, you can connect to a pre-existing Juju controller (created with the [`juju` CLI](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/juju-cli/)) and then go ahead and use it to do Juju things -- easy deploy, configure, integrate, scale, etc., applications on any Juju-supported cloud (Kubernetes or otherwise) using [charms](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/charm/).
 
 `terraform-provider-juju` combines the power of Terraform -- comprehensive infrastructure management, declaratively -- with the power of Juju -- easy systems management, from Day 0 to Day n.