docs: fill in gaps from v15-16

docs-rtd/.custom_wordlist.txt

@@ -1,16 +1,19 @@
 CIDRs
 CPUs
-Hashicorp
-MicroK
-Multipass
-SREs
-TLS
-Terraform
-Unexpose
 declaratively
+Hashicorp
+JAAS
+JIMM
 juju
+kubeconfig
 localhost
 macOS
+MicroK
+Multipass
 natively
+Terraform
 terraform
+SREs
+TLS
+Unexpose
 unexpose

docs-rtd/conf.py

@@ -109,7 +109,7 @@
     # Product tag image; the orange part of your logo, shown in the page header
     #
     # TODO: To add a tag image, uncomment and update as needed.
-    # 'product_tag': '_static/tag.png',
+    'product_tag': '_static/juju-logo-no-text.png',
     # Your Discourse instance URL
     #
     # TODO: Change to your Discourse instance URL or leave empty.
@@ -236,9 +236,24 @@
 extensions = [
     "canonical_sphinx",
     "sphinxcontrib.cairosvgconverter",
+    # Make it possible to link to related RTD projects using their internal anchors
+    # with, e.g., {external+ops:ref}`manage-configurations`:
+    'sphinx.ext.intersphinx',
 ]
 
 
+##################################
+# sphinx.ext.intersphinx options #
+##################################
+
+intersphinx_mapping = {
+    'juju': ('https://canonical-juju.readthedocs-hosted.com/en/latest/', None),
+    'pyjuju': ('https://pythonlibjuju.readthedocs.io/en/latest/', None),
+    'jaas': ('https://canonical-jaas-documentation.readthedocs-hosted.com/en/latest/', None),
+    'charmcraft': ('https://canonical-charmcraft.readthedocs-hosted.com/en/latest/', None),
+    'ops': ('https://ops.readthedocs.io/en/latest/', None),
+}
+
 # Excludes files or directories from processing
 
 exclude_patterns = [

docs-rtd/howto/index.md

@@ -6,19 +6,23 @@
 ```{toctree}
 :maxdepth: 2
 
-Install and manage terraform-provider-juju <install-and-manage-terraform-provider-juju>
-Manage credentials <manage-credentials>
-Manage models <manage-models>
-Manage charms <manage-charms>
-Manage charm resources <manage-charm-resources>
-Manage applications <manage-applications>
-Manage relations <manage-relations>
-Manage offers <manage-offers>
-Manage units <manage-units>
-Manage machines <manage-machines>
-Manage SSH keys <manage-ssh-keys>
-Manage users <manage-users>
-Manage secrets <manage-secrets>
+manage-terraform-provider-juju
+manage-clouds
+manage-credentials
+manage-controllers
+manage-models
+manage-charms
+manage-charm-resources
+manage-applications
+manage-relations
+manage-offers
+manage-units
+manage-machines
+manage-ssh-keys
+manage-users
+manage-groups
+manage-service-accounts
+manage-secrets
 ```
 
 <!--

docs-rtd/howto/manage-applications.md

@@ -1,7 +1,20 @@
 (manage-applications)=
-# How to manage applications
+# Manage applications
 
-> See also: [`juju` | Application](https://juju.is/docs/juju/application)
+> See also: {external+juju:ref}`Juju | Application <application>`
+
+## Reference an externally managed application
+
+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" {
+  model      = juju_model.development.name
+  application = "mattermost"
+}
+```
+
+> See more: [`juju_application` (data source)](https://registry.terraform.io/providers/juju/juju/latest/docs/data-sources/application)
 
 ## Deploy an application
 
@@ -19,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`:
 
@@ -40,7 +53,7 @@ resource "juju_application" "this" {
 
 
 ## Configure an application
-> See also: [`juju` | Application configuration](https://juju.is/docs/juju/configuration#heading--application-configuration)
+> See also: {external+juju:ref}`Juju | Application configuration <application-configuration>`
 
 To configure an application, in its resource definition add a configuration map with the `key=value` pairs you want (from the list of configurations available for the charm).
 
@@ -53,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)
@@ -63,12 +76,12 @@ resource "juju_application" "this" {
 (scale-an-application)=
 ## Scale an application
 
-> See also: [`juju`| Scaling](https://juju.is/docs/juju/scaling)
+> See also: {external+juju:ref}`Juju | Scaling <scaling>`
 
 ### 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)=
@@ -80,9 +93,9 @@ 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)
+> See also: {external+juju:ref}`Juju | High availability (HA) <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/)
 
@@ -125,8 +138,8 @@ resource "juju_application" "this" {
 
   expose = {
     endpoints = "..., ..."
-    spaces = 
-    cidrs = 
+    spaces =
+    cidrs =
   }
 }
 ```
@@ -143,7 +156,7 @@ resource "juju_application" "this" {
 (manage-constraints-for-an-application)=
 ## Manage constraints for an application
 
-> See also: [`juju` | Constraint](https://juju.is/docs/juju/constraint)
+> See also: {external+juju:ref}`Juju | Constraint <constraint>`
 
 
 To set constraints for an application, in its resource definition specify a `constraints` attribute followed by a quotes-enclosed, space-separated list of key=value pairs. For example:
@@ -167,8 +180,7 @@ resource "juju_application" "this" {
 
 ## Change space bindings for an application
 
-> See also: [`juju` | Binding](https://juju.is/docs/juju/binding)
-
+> See also: {external+juju:ref}`Juju | Space <space>`
 
 To set space bindings for an application, in its resource definition specify an `endpoint_bindings` with a `space` key, to set a default for the entire application, and/or a `space` and an `endpoint` key, to set the space binding for a particular application endpoint. For example, below all the application's endpoints are bound to the `public` space except for the `juju-info` endpoint, which will be bound to the `private` space:
 
@@ -197,19 +209,15 @@ 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`
 
 (remove-an-application)=
 ## Remove an application
 
-> See also: [`juju` | Removing things](https://juju.is/docs/juju/removing-things)
-
+> See also: {external+juju:ref}`Juju | Removing things <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)
-
-
-> <small>Contributors: @achilleasa , @cderici, @james-garner, @hmlanigan , @nvinuesa , @pedroleaoc , @pmatulis , @stephanpampel , @timClicks , @tmihoc </small>

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

@@ -1,7 +1,7 @@
 (manage-charm-resources)=
-# How to manage charm resources
+# Manage charm resources
 
-> See also: [`juju` | Resource (charm)](https://juju.is/docs/juju/charm-resource)
+> See also: {external+juju:ref}`Juju | Resource (charm) <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.
 
@@ -14,7 +14,7 @@ To specify the resource(s) to be deployed with your charm, in your Terraform pla
 resource "juju_application" "application_one" {
   name = "my-application"
   model = juju_model.testmodel.name
-  
+
   charm {
     name = "juju-qa-test"
     channel = "2.0/edge"
@@ -37,11 +37,3 @@ About `charm > revision` and `resources`:
 ```
 
 > See more: [`juju_application > resources`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application#resources)
-
-
-
-
-
-<br>
-
-> <small>**Contributors:** @cderici, @hmlanigan, @tmihoc </small>

docs-rtd/howto/manage-charms.md

@@ -1,8 +1,10 @@
 (manage-charms)=
-# How to manage charms
+# Manage charms
+
+> See also: {external+juju:ref}`Juju | Charm <charm>`
 
 (deploy-a-charm)=
-## Deploy a charm 
+## Deploy a charm
 
 ```{important}
 
@@ -45,13 +47,8 @@ resource "juju_application" "this" {
 
 > See more: [`juju_application` > `charm` > nested schema ](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/application#nested-schema-for-charm)
 
-## Remove a charm 
+## Remove a charm
 
 As a charm is just the *means* by which (an) application(s) are deployed, there is no way to remove the *charm* / *bundle*. What you *can* do, however, is remove the *application* / *model*.
 
 > See more: {ref}`remove-an-application`, {ref}`destroy-a-model`
-
-
-<br>
-
-> <small>**Contributors:** @aflynn, @hmlanigan, @tmihoc </small>

docs-rtd/howto/manage-clouds.md

@@ -0,0 +1,48 @@
+(manage-clouds)=
+# Manage clouds
+
+> See also: {external+juju:ref}`Juju | Cloud <cloud>`
+
+(add-a-kubernetes-cloud)=
+## Add a Kubernetes cloud
+
+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)
+
+(manage-access-to-a-cloud)=
+## Manage access to a cloud
+
+
+```{note}
+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:
+
+```terraform
+resource "juju_jaas_access_cloud" "development" {
+  cloud_name       = "aws"
+  access           = "can_addmodel"
+  users            = ["foo@domain.com"]
+  groups           = [juju_jaas_group.development.uuid]
+  service_accounts = ["Client-ID-1", "Client-ID-2"]
+}
+```
+
+> See more: [`juju_jaas_access_cloud`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/jaas_access_cloud), [JAAS | Cloud access levels](https://canonical-jaas-documentation.readthedocs-hosted.com/en/latest/reference/authorisation_model/#cloud)

docs-rtd/howto/manage-controllers.md

@@ -0,0 +1,24 @@
+(manage-controllers)=
+# Manage controllers
+
+> See also: {external+juju:ref}`Juju | Controller <controller>`
+
+(manage-access-to-a-controller)=
+## Manage access to a controller
+
+```{note}
+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:
+
+```terraform
+resource "juju_jaas_access_controller" "development" {
+  access           = "administrator"
+  users            = ["foo@domain.com"]
+  groups           = [juju_jaas_group.development.uuid]
+  service_accounts = ["Client-ID-1", "Client-ID-2"]
+}
+```
+
+> See more: [`juju_jaas_access_controller`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/jaas_access_controller), [JAAS | Controller access levels](https://canonical-jaas-documentation.readthedocs-hosted.com/en/latest/reference/authorisation_model/#controller)

docs-rtd/howto/manage-credentials.md

@@ -1,7 +1,7 @@
 (manage-credentials)=
-# How to manage credentials
+# Manage credentials
 
-> See also: [Credential](https://juju.is/docs/juju/credential)
+> See also: {external+juju:ref}`Juju | Credential <credential>`
 
 
 ## Define a credential
@@ -59,9 +59,4 @@ To update a credential, in your Terraform plan, update its resource definition.
 
 To remove a credential, remove its resource definition from your Terraform plan.
 
-> See more: [Resource `juju_credential`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/credential)
-
-
-<br>
-
-> <small>**Contributors:** @cderici, @erik-lonroth , @pedroleaoc, @pmatulis, @timclicks, @tmihoc, @wallyworld </small>
+> See more: [`juju_credential`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/credential)