Skip to content
This repository was archived by the owner on Jan 19, 2026. It is now read-only.

docs: update add-model how-to#124

Closed
kian99 wants to merge 2 commits intocanonical:v3from
kian99:add-model-info
Closed

docs: update add-model how-to#124
kian99 wants to merge 2 commits intocanonical:v3from
kian99:add-model-info

Conversation

@kian99
Copy link
Contributor

@kian99 kian99 commented Dec 12, 2025

Description

This PR updates our manage-models how-to with more and new information after recent changes to our permission model.

Some of this information was existing behavior that wasn't documented and other bits are new. In summary I was aiming to document,

  • How permissions for model creation are defined.
  • How controller selection is performed.
  • How to specify a specific controller to host your model.

Fixes JUJU-8867

@kian99 kian99 requested a review from tmihoc December 12, 2025 08:16
Copy link
Member

@tmihoc tmihoc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for this.

Do see my comment and the suggested rewrite.

Happy to take another look, if you want. Approving now just so that you're not blocked.

--ignore "$(SPHINXDIR)/**" \
--ignore "$(BUILDDIR)/**" \
"$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
# Does not depend on $(BUILDDIR) to rebuild properly at every run.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be good to contribute this upstream: https://github.com/canonical/sphinx-docs-starter-pack/blob/8877f8511f359be35363d3347705e3ddab06da6a/docs/Makefile#L81

Do you want to put up the PR yourself? If not, I can do it too, mentioning you in the credits, of course.

define audit_log_viewer: [user, user:*, group#member, role#assignee] or administrator
define controller: [controller]
define can_addmodel: [user, user:*, group#member, role#assignee] or administrator

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should add a matching line to the table in https://canonical-ubuntu-documentation-library--124.com.readthedocs.build/jaas/124/howto/manage-permissions/#add-a-permission too. Maybe also add one more example to feature the explicit model+controller mention.

# Manage models

(creating-a-model)=
## Creating a model
Copy link
Member

@tmihoc tmihoc Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on our chat:

Let's make this fit better into this how-to (I'll write it in a way where you can just copy paste it into the doc):

(create-a-model)=
## Create a model

```{mermaid}
flowchart LR
    U["User </br> (limited controller access)"]
    subgraph Controllers
        C1["Controller A</br>(supports openstack)"]
        C2["Controller B</br>(supports openstack)"]
        C3["Controller C</br>(does NOT support openstack)"]
        C4["Controller D</br>(supports openstack)"]
    end
    U -- access --> C2
    U -. no access .-> C1
    U -. no access .-> C4
    U -. no access .-> C3
    classDef ok fill:#b3e6b3,stroke:#2d662d,stroke-width:1px;
    classDef no fill:#f2b3b3,stroke:#662d2d,stroke-width:1px;
    class C1,C2,C4 ok;
    class C3 no;
    %% Model placement result
    subgraph Result
        M[(my-model)]
    end
    C2 -- selected for model --> M
```
_Adding a model in JAAS requires permissions on a cloud as well as a controller. In this example multiple controllers (in green) support the `openstack` cloud while controller C (in red) does not. The dotted lines show that user does not have access to any controller except controller B. Based on these 2 factors the only valid placement is controller B._

To create a model:

1. Make sure you have the necessary permissions:

- `can_addmodel` permission on the target cloud
- `can_addmodel` permission on one or more controllers that support that cloud

> See more: {ref}`verify-a-permission`

Note: By default, all users have add-model access to all clouds in JAAS; however, they have no default access to any controllers.

2. Add the model using the `jaas add-model` command, optionally specifying a target controller:
For example:

```
# View all the controllers you have access to:
juju jaas list-controllers
# Add your model to the controller of your choice:
juju jaas add-model --target-controller <mytargetcontroller>
```

> See more: [ADD REF TO JAAS ADD-MODEL COMMAND]

Note: If you don't specify a controller: 
a. If you only have access to one controller, JIMM will automatically connect it to that controller.  
b. If you have access to multiple controllers, JIMM will choose one for you, prioritizing controllers within the cloud so as to reduce latency or selecting randomly when there are multiple valid options..

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've made this change, thanks!
@ale8k Pointed out that we have an inconsistency in JIMM. When you add a controller to JIMM we grant everyone with access to the clouds on that controller. But when you add a cloud later, we don't grant everyone with access. Until we clean this up I've removed the line "Note: By default, all users have add-model access to all clouds in JAAS; however, they have no default access to any controllers."

We also don't yet have a jaas add-model command, but we will soon. I think we can either leave this as a draft until then or land it and soon the command will come, lmk what you think on that @tmihoc

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say, without that command this story isn't really meaningful. So I'd keep it as a draft till then.

Use the `juju jaas list-controllers` command to list the controllers you have
access to.

(migrate-a-model-to-jaas)=
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think all of this is now covered in the rewrite suggested in my previous comment. Imo no need for an explanation doc, unless you want to dive in deeper into how this ties into JAAS' authentication and authorization paradigm as opposed to Juju's paradigm (the things you were beginning to tell me about).


type cloud
relations
define controller: [controller]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. Ngl seeing consistency hits different. Ty for this lol.

- The `can_addmodel` permission on the target cloud.
- The `can_addmodel` permission on one or more controllers that support that cloud.

By default, all users have add-model access to all clouds in JAAS.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't true right? Isn't it the case that if you:

  • You add a controller, it has a cloud, but that one can be used by all users
  • You add a cloud, but then no one can use it until granted?

Copy link
Contributor Author

@kian99 kian99 Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah you're right.
Seems like an oversight on our part and we should be consistent in both scenarios.

@kian99
Copy link
Contributor Author

kian99 commented Jan 16, 2026

Moved to canonical/jimm#1808

@kian99 kian99 closed this Jan 16, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants