[Tutorial] Multi-user basic setup


#1

This is a tutorial in connection with the multi-user framework of Juju. It’s an introduction to using multiple users that people may find useful. Feedback appreciated.

Multi-user basic setup - tutorial

This tutorial will give an overview of how Juju can be used with one person
assuming the role of a traditional administrator and a second person acting as
the Juju operator. The administrator creates the controller, creates users,
and grants user permissions whereby the operator is responsible for creating
models and installing software.

The following topics will be covered:

  • Controller creation and the initial controller administrator
  • User creation and controller registration
  • User login, logout, and password changing
  • User model creation
  • User charm deployment

Controller creation and the initial controller administrator

Besides resulting in a new controller the bootstrap command sets up a Juju
user called ‘admin’ with controller permissions of ‘superuser’. This is the
initial controller administrator.

Here we’ll add credentials and then create a GCE-based controller:

juju add-credential google -f credentials-administrator.yaml
juju bootstrap google gce

In the above the credentials file contains a single credential for the ‘google’
cloud, allowing it to become the default credential in the subsequent
bootstrap command.

Inspecting the controller’s users with the users command allows us to confirm
the above information:

juju users

Example output:

Controller: gce

Name    Display name  Access     Date created   Last connection
admin*  admin         superuser  2 minutes ago  just now

Note that the new administrator does not have a password per se. Create one
now:

juju change-user-password

User creation and controller registration

Let the administrator now create a regular user called ‘tom’:

juju add-user tom

The output includes a string (token) to give to the intended operator of the
new user. This will enable the operator to add the controller to their own Juju
client running on a separate host.

Sample output:

User "tom" added
Please send this command to tom:
    juju register MGcTA3RvbTA5ExQzNS4yMzcuMTY1LjI[...]

"tom" has not been granted access to any models. You can use "juju grant" to grant access.

Important:
The client host must be able to contact the controller host on TCP port
17070 in order for controller registration to succeed. This is the case for
any client-controller communication.

Registration is done with the register command. On a separate host, then:

juju register MGcTA3RvbTA5ExQzNS4yMzcuMTY1LjI[...]

Example output:

Enter a new password: ******
Confirm password: ******
Enter a name for this controller [gce]: 
Initial password successfully set for tom.

Welcome, tom. You are now logged into "gce".

There are no models available. You can add models with
"juju add-model", or you can ask an administrator or owner
of a model to grant access to that model with "juju grant".

User login, logout, and password changing

A newly-created user is granted controller access of ‘login’ out of the box
(implicitly: juju grant -c gce tom login) . So besides logging in, the user
cannot do much else.

Registration implies a controller login (as can be seen by the previous
command’s messaging). To log out, use the logout command:

juju logout

A login session also expires after a fixed amount of time (24 hours).

To log back in, use the login command with the username as argument. Provide
the password that was set up during registration:

juju login -u tom

Supply a controller name (-c gce) if there is more than one controller
registered with the client.

Change the user’s password with the change-user-password command:

juju change-user-password

User model creation

In order for the user to be able to add models the administrator must grant
‘add-model’ controller access:

juju grant tom add-model

Yet before the remote operator is able to create a model he will first need to
add a credential to Juju. In a single-user setup this is done prior to
controller creation, but in this context the operator is devoid of a
credential.

On the (user) operator’s host, add a credential and then add a model:

juju add-credential google -f credentials-operator.yaml
juju add-model gce-model-1

In the above the credentials file contains a single credential for the ‘google’
cloud, allowing it to become the default credential in the subsequent
add-model command.

User model SSH access

The operator user can now connect, using Juju’s ssh command, to any machine
that may get created within their new model. This is standard Juju behaviour
that the model creator always enjoys. Note, however, that the SSH keys
necessary for this to work are found within the client system’s filesystem at
~/.local/share/juju/ssh/juju_id_rsa.pub (and ~/.ssh/id_rsa.pub if it
existed at the time of model creation).

Verify SSH access now on the operator host:

juju add-machine
juju ssh 0

Above we assume the machine that was added got assigned an ID of ‘0’ (the
default for the first machine in a model).

User charm deployment

The operator user can now deploy charms as normal. See Deploying applications for help.

That’s the end of this tutorial!

Further reading

See the full documentation at Working with multiple users.


#2

@pmatulis Great start!

A few thoughts:

  1. Title the post [Tutorial] which makes these posts stand out in the forum. That is really helpful until there is a separate category at discourse.
  2. Machine constraints for the controller bootstrap node are important. mem,cpu,disk etc. Sizing the controllers wrong causes problems.
  3. In what cases does the user need cloud-credentials, vs, when not? Its good to know that users in a multiuser settings can operate juju without acctually having an own account in lets say “maas” or “gce” or “aws”. I think its only when a user needs “add-model” ACL, but that is good to know.
  4. Perhaps add that performing “juju grant -c gce tom login” is implicit if adding local users (?). In my case, all my users are in LDAP - so I strictly need to do that step (or the users will not be granted access to the controller at all).
  5. A means how to “re-register” with a controller is a common thing we struggle with when testing these things. E.g. how do I get a proper “controller.yaml” and “cloud.yaml” re-created. if I lose or need to distribute this to other clients if I never do the “add-user” step (as is the case with users in an LDAP)? At the moment, I need to manually edit/create these yaml files to get LDAP users “aware” of where the controller/cloud is located. This is even more true if you don’t use a public cloud, but your own “maas” for example.

FYI:

Together with @hallback, we have managed to produce a multi-user environment, backed by “candid” connected to our coorporate MS Active Directory LDAP with proper TLS/SSL. We have connected both a “maas” type cloud and a “vsphere” type to this. This is likely a very common enterprise situation and we are starting to like it alot.

There are a few more steps needed to get that to work and hopefully we can publish a tutorial on this down the road.


#3

Thank you for your feedback Erik.

Just “[Tutorial]”? No description?

Yeah. I hear you. There’s lots that can be added but I try to keep a tutorial focused on its objective to avoid losing readers.

Yes. Credentials are always associated with models. Even when you create a controller you are setting up models (‘controller’ and ‘default’). I go over this in the core docs. Again, I try not to do too much extra teaching in a tutorial. My vision is that a tutorial does not teach new things. They are walkthroughs that make use of existing material.

This is a juicy bit of information from the field. I do mention it obliquely (“A newly-created user is granted controller access of ‘login’ out of the box.”) but I can be more explicit. Thank you.

I don’t see any way other than manual methods. Are you asking for new Juju functionality that will generate these files on demand or for having manual steps spelled out along with documented use cases?

Yes, such a writeup would definitely be welcomed.

Erik, I know you filed a couple of bugs last year but I encourage you to file more (tracker)!