docs: fill in gaps from v15-16 #658

tmihoc · 2025-01-28T13:59:49Z

Description

This PR fills in docs gaps from v15-16 and makes a few other small updates. Specifically, it:

adds how-to guides for all the resources and data sources that were not yet featured (this includes all the recent jaas bits but also all the data sources and things such as juju_kubernetes_cloud and also refactors content / creates new docs as needed, e.g., with jaas users are just one of 3 entities that can be given access to things, so I've reorganized all that content so it'll better reflect that)
updates the Juju links to point to the new Juju RTD
removes the Contributors section at the end of each how-to (the handles had no meaning outside of Discourse, plus Daniele we don't need to track manually anymore)

Type of change

Docs.

QA steps

In terraform-provider-juju/docs-rtd, run make run to preview the changes in a browser.

alesstimec

LGTM with a few suggestions.. Thank you!

alesstimec · 2025-01-30T09:43:56Z

docs-rtd/howto/manage-groups.md

+
+## 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:


Suggested change

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:

alesstimec · 2025-01-30T09:45:23Z

docs-rtd/howto/manage-groups.md

+(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:


Thinking that maybe we should reword it to make it cleared that by "adding access to a group" we manage group membership.. "granting" somebody access to a group effectively makes them a member of that group.

Well, that is so only because the only valid access level is "member". Will that still be all in the future?

I moved the note about member being the only valid level higher, before the example, and rephrased it:

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.

alesstimec · 2025-01-30T09:50:07Z

docs-rtd/howto/manage-offers.md


-> See more: [`juju_offer`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/offer)
+### 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:


a suggestion for all Juju VS JAAS sections:
"When applying a Terraform plan to a Juju controller"
vs
"When applying a Terraform plan to a JAAS controller"

Because when you say "When using Juju alone" it sounds to me like you're using the Juju CLI, not the provider.

Updated the section intro, subsection titles, and subsection intro lines to align with this.

alesstimec · 2025-01-30T09:51:24Z

docs-rtd/howto/manage-offers.md

+## Remove an offer
+> Who: User with [offer `admin` access](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/user/#user-access-offer-admin).
+
+To remove an offer, in your Terraform plan, remove its resource definition.


unless they used the offer data source in which case will need to use external tools to remove it

As discussed in our call, I've updated the docs to not have any mention of data sources in the Remove an x sections. Also, for all entities that can be referenced through a data source, I've updated the Manage x > Reference... section to have the better phrasing we agreed upon ("outside of the current Terraform plan").

tmihoc

Had a follow-up question about how to handle the remove sections (with the data source and resource split).

tmihoc · 2025-01-30T12:11:33Z

docs-rtd/howto/manage-groups.md

+
+## 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:


tmihoc · 2025-01-30T12:13:13Z

docs-rtd/howto/manage-groups.md

+(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:


Well, that is so only because the only valid access level is "member". Will that still be all in the future?

tmihoc · 2025-01-30T12:15:27Z

docs-rtd/howto/manage-groups.md

+(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:


I moved the note about member being the only valid level higher, before the example, and rephrased it:

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.

tmihoc · 2025-01-30T12:28:23Z

docs-rtd/howto/manage-offers.md


-> See more: [`juju_offer`](https://registry.terraform.io/providers/juju/juju/latest/docs/resources/offer)
+### 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:


Updated the section intro, subsection titles, and subsection intro lines to align with this.

tmihoc · 2025-01-31T15:08:11Z

/merge

tmihoc · 2025-01-31T15:42:01Z

/merge

tmihoc · 2025-01-31T16:09:34Z

/merge

tmihoc · 2025-01-31T16:46:22Z

/merge

kian99 · 2025-02-03T10:07:26Z

@hmlanigan @alesstimec The test TestAcc_ResourceApplication_UpdatesRevisionConfig is failing, because the github-runner charm has changed and no longer has the runner-storage config valid.
From the test below, I see we are pinning a revision but it seems that it is pulling the charm from latest/edge where you can see the config values in my screenshot below.

func TestAcc_ResourceApplication_UpdatesRevisionConfig(t *testing.T) {
	if testingCloud != LXDCloudTesting {
		t.Skip(t.Name() + " only runs with LXD")
	}

	modelName := acctest.RandomWithPrefix("tf-test-application")
	appName := "github-runner"
	configParamName := "runner-storage"

	resource.ParallelTest(t, resource.TestCase{
		PreCheck:                 func() { testAccPreCheck(t) },
		ProtoV6ProviderFactories: frameworkProviderFactories,
		Steps: []resource.TestStep{
			{
				Config: testAccResourceApplicationWithRevisionAndConfig(modelName, appName, 88, "", "", ""),

…nd service accounts

tmihoc force-pushed the docs-fill-in-gaps-from-v15-16 branch 3 times, most recently from a392e52 to aaeb786 Compare January 28, 2025 14:12

hmlanigan self-requested a review January 28, 2025 15:35

tmihoc force-pushed the docs-fill-in-gaps-from-v15-16 branch from aaeb786 to 11fc2bc Compare January 29, 2025 15:22

alesstimec approved these changes Jan 30, 2025

View reviewed changes

tmihoc commented Jan 30, 2025

View reviewed changes

tmihoc force-pushed the docs-fill-in-gaps-from-v15-16 branch 2 times, most recently from bf3bb7f to 8ff09c9 Compare January 31, 2025 12:50

hmlanigan approved these changes Jan 31, 2025

View reviewed changes

tmihoc force-pushed the docs-fill-in-gaps-from-v15-16 branch from 8ff09c9 to 5d84513 Compare January 31, 2025 15:40

tmihoc force-pushed the docs-fill-in-gaps-from-v15-16 branch from 5d84513 to ffc4f61 Compare February 4, 2025 08:26

tmihoc added 4 commits February 18, 2025 13:54

docs: add initial content for all the data sources

60ab096

docs: add how-tos for all the access bits and everything for groups a…

7755501

…nd service accounts

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

8e442b1

docs: set up intersphinx, update setup and teardown links

fbe123b

tmihoc force-pushed the docs-fill-in-gaps-from-v15-16 branch from ffc4f61 to fbe123b Compare February 18, 2025 13:09

tmihoc added 3 commits February 18, 2025 14:14

docs: update rtd logo

bb485d7

docs: update jaas controller to juju controller added to jimm

5b86400

docs: update all juju links to intersphinx

1d5911b

tmihoc force-pushed the docs-fill-in-gaps-from-v15-16 branch from 328dbff to 1d5911b Compare February 18, 2025 13:57

docs: add custom words

9e41e3b

alesstimec added the state/codefreeze this pr cannot land until the code freeze has lifted. label Feb 18, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: fill in gaps from v15-16 #658

docs: fill in gaps from v15-16 #658

tmihoc commented Jan 28, 2025

alesstimec left a comment

alesstimec Jan 30, 2025

tmihoc Jan 30, 2025

alesstimec Jan 30, 2025

tmihoc Jan 30, 2025

tmihoc Jan 30, 2025

alesstimec Jan 30, 2025

tmihoc Jan 30, 2025

alesstimec Jan 30, 2025

tmihoc Jan 31, 2025

tmihoc left a comment

tmihoc Jan 30, 2025

tmihoc Jan 30, 2025

tmihoc Jan 30, 2025

tmihoc Jan 30, 2025

tmihoc commented Jan 31, 2025

tmihoc commented Jan 31, 2025

tmihoc commented Jan 31, 2025

tmihoc commented Jan 31, 2025

kian99 commented Feb 3, 2025 •

edited

Loading


		## 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:

docs: fill in gaps from v15-16 #658

Are you sure you want to change the base?

docs: fill in gaps from v15-16 #658

Conversation

tmihoc commented Jan 28, 2025

Description

Type of change

QA steps

alesstimec left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tmihoc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tmihoc commented Jan 31, 2025

tmihoc commented Jan 31, 2025

tmihoc commented Jan 31, 2025

tmihoc commented Jan 31, 2025

kian99 commented Feb 3, 2025 • edited Loading

kian99 commented Feb 3, 2025 •

edited

Loading