[LEAP Hub] Allow for profile list options based on GitHub team membership

[choldgraf]

Background and proposal

The LEAP Hub has different sub-communities within its user community. Some of them require access to more complex infrastructure than others, and they'd like to offer different environments to some users over others.

Specifically, they'd like this breakdown of github team membership and machine types (ref: #1050 (comment)):

tier	privileges
Public tier leap-stc/leap-pangeo-users	Access to "Small" and "Medium" machine types
Research tier leap-stc/leap-pangeo-research	Access to all machine types plus GPU option

So from a user's perspective, the end-result they would like is something like:

• A user logs in to the hub, authenticating with their GitHub handle
• At the profile list page, they are presented with a different list of options based on their GitHub team membership
• They can then select an option like normal and proceed.

Implementation guide and constraints

@consideRatio provided a nice description of the solution in this Discourse comment.

Here's the major parts of this approach:

Problem 1 - Adjust presented server options based on user

What if you want to present different server options to different users, based on some property of the user? Just setting c.KubeSpawner.profile_list / singleuser.profileList won't do because then all users would get the same options.

The solution to this is to update c.KubeSpawner.options_form with a custom function that first updates the the_users_spawner_instance.profile_list based on logic that involve the user information.

Common section for examples below

The examples below assume we can request a "scope" called "gpu_access", which is supposed to return a "claim" with the same name as a true or false value.

# This snipped assumes a OAuthenticator based Authenticator, and the scopes will
# vary and this is just an example.
#
# - openid is common for OpenID Connect based authentication
# - profile, email are both commonly available scopes to request
# - gpu_access is entirely custom
#
c.OAuthenticator.scopes = ["openid", "profile", "email", "gpu_access"]

Solution to problem 1

To present JupyterHub server spawn options based on the user

# To adjust the spawn options presented to the user, we must create a custom
# options_form function, and this example demonstrates how!
#
#
#
# profile_list (KubeSpawner class) can be configured as a convenience to
# generate set HTML for the options_form configuration (Spawner class).
#
# If options_form is set (or indirectly set through profile_list), it is the
# HTML that users are presented with when users have signed in and want to start
# a server.
#
# While options_form is allowed to be a HTML string, it can also be a callable
# function, that when called generates HTML. If a callable function return a
# falsy value, no form will be rendered.
#
# In this custom options_form function, we will make a decision based on user
# information, update profile_list, and rely on the profile_list logic to render
# the HTML for us.
#
async def custom_options_form(spawner):
    # See the pre_spawn_hook example for more ways to get information about the
    # user
    auth_state = await spawner.user.get_auth_state()
    user_details = auth_state["oauth_user"]
    gpu_access = user_details.get("gpu_access", False)

    # Declare the common profile list for all users
    spawner.profile_list = [
        {
            'display_name': 'CPU server',
            'slug': 'cpu',
            'default': True,
        },
    ]

    # Dynamically update profile_list based on user
    if gpu_access:
        spawner.log.info(f"GPU access options added for {username}.")
        spawner.profile_list.extend(
            [
                {
                    'display_name': 'GPU server',
                    'slug': 'gpu',
                    'kubespawner_override': {
                        'image': 'training/datascience:my_tag',
                    },
                },
            ]
        )

    # Let KubeSpawner inspect profile_list and decide what to return, it
    # will return a falsy blank string if there is no profile_list,
    # which makes no options form be presented.
    #
    # ref: https://github.com/jupyterhub/kubespawner/blob/37a80abb0a6c826e5c118a068fa1cf2725738038/kubespawner/spawner.py#L1885-L1935
    return spawner._options_form_default()

# Don't forget to ask KubeSpawner to make use of this custom hook
c.KubeSpawner.options_form = custom_options_form

Opportunity to generalize

Note that while this is a request for a specific hub, the general pattern of "allow some users access to a subset of environments" will likely be very common. As we do this work, we should keep an eye on how to document and/or abstract this process to be repeatable with minimal extra toil.

Updates and ongoing work

• Get [GitHub] Add populate_teams_in_auth_state option jupyterhub/oauthenticator#498 merged upstream to get list of user teams when they log in
• Pull that in to our JupyterHub image once it's merged so we can keep going
• Write some generic code that can restrict profile_list options based on team membership

[consideRatio]

Note how we in this example have this line:

    auth_state = await spawner.user.get_auth_state()

If we want to make decisions based on a GitHubOAuthenticator which is informed about what teams etc a user is part of, we should probably work to address the feature request: jupyterhub/oauthenticator#492

[choldgraf]

Ah-ha good catch @consideRatio , thanks for the reminder. Anything else that you think is needed in order to implement this within our hubs?

[consideRatio]

@choldgraf no I think that is all it takes!

[choldgraf]

Note - there was some other conversation about this in the original thread here:

• [New Hub] LEAP Pangeo #1050 (comment)

[yuvipanda]

@rabernat I just opened jupyterhub/oauthenticator#498 which should get us most of the way here.

[yuvipanda]

ok, #1239 sets this up! I've 'small' and 'medium' available to leap-stc:leap-pangeo-users while 'huge' and 'large' are available only to leap-stc:leap-pangeo-research. Everything is available to 2i2c-org:tech-team though, so I'll need someone to actually test this. I've deployed this on https://staging.leap.2i2c.cloud/ - can you test, @rabernat?

[damianavila]

@rabernat, can you confirm if you tested it? Thanks!

[rabernat]

Yes I tested it and it works as expected.