Documentation examplifies admin:services scope - but it doesn't exist

[ktaletsk]

Bug description

I am trying to migrate to JupyterHub 2.1 from 2.0 and realized that my admin service does not work. I had the following configuration:

 c.JupyterHub.services = [
        {
            "name": "service-token",
            "admin": True,
            "api_token": ADMIN_SERVICE_ACC,
        },
       ...
    ]

Following the instructions in the docs, I replaced the service and added the role:

c.JupyterHub.services = [
    {
        "name": "service-token",
        "api_token": ADMIN_SERVICE_ACC,
    },
]

c.JupyterHub.load_roles = [
    {
        "name": "admin-role",
        "scopes": [
            "admin:users",
            "admin:services",
        ],
        "services": [
            "service-token",
        ],
    }
]

After that, I am getting the error from JupyterHub:

[E 2022-03-01 17:22:36.355 JupyterHub app:3282]
    Traceback (most recent call last):
      File "/opt/conda/lib/python3.7/site-packages/jupyterhub/app.py", line 3279, in launch_instance_async
        await self.initialize(argv)
      File "/opt/conda/lib/python3.7/site-packages/jupyterhub/app.py", line 2812, in initialize
        await self.init_role_creation()
      File "/opt/conda/lib/python3.7/site-packages/jupyterhub/app.py", line 2090, in init_role_creation
        roles.create_role(self.db, role)
      File "/opt/conda/lib/python3.7/site-packages/jupyterhub/roles.py", line 291, in create_role
        _check_scopes(*scopes, rolename=role_dict['name'])
      File "/opt/conda/lib/python3.7/site-packages/jupyterhub/roles.py", line 235, in _check_scopes
        raise KeyError(f"Scope '{scope}' {log_role} does not exist")
    KeyError: "Scope 'admin:services' for role admin-role does not exist"

And indeed, I cannot find mentions of admin:service nowhere else in the documentation or the code, other than in the chapter about admin services. The list of available scopes does have admin:users, but not the admin:services.

Is this

• a bug
• incorrect documentation
• mistake on my part ? How does one set a service with admin privileges?

Your personal set up

jupyterhub 2.1.1

[consideRatio]

Could it be that you need to configure load_roles before services - because there is validation logic running just when you set c.JupyterHub.services?

[ktaletsk]

I just tried 2 things:

1. Remove admin:services from my admin-role. Error went away.
2. Keep admin:services and load roles before services. Error persists.

[consideRatio]

I think the answer is admin:services doesn't exist. See this list: https://jupyterhub.readthedocs.io/en/stable/rbac/scopes.html#available-scopes

What kind of change did you look to do? Use the JupyterHub REST API to add a JupyterHub registered service dynamically?

[ktaletsk]

@consideRatio thanks for clarification. If the scope does not exist, we should update the documentation here: https://github.com/jupyterhub/jupyterhub/blob/2dc2c99b4a8965e5526e37e8bff35842e937a838/docs/source/reference/rest.md?plain=1#L110-L123

I was trying to get the equivalent behavior to to the old (v1.x) admin services. In particular, I have cull-idle services and generic admin service which is used to read users, groups and launch named servers. I guess, this is my hint to move on from the old ways and start using RBAC in earnest instead of blanket admin permissions.

For example, cull-idle is described in docs without giving admin access:

c.JupyterHub.services = [
    {
        "name": "idle-culler",
        "command": [
            sys.executable, "-m",
            "jupyterhub_idle_culler",
            "--timeout=3600"
        ],
    }
]

c.JupyterHub.load_roles = [
    {
        "name": "idle-culler",
        "description": "Culls idle servers",
        "scopes": ["read:users:name", "read:users:activity", "servers"],
        "services": ["idle-culler"],
    }
]

Thanks for the help and we can probably close the issue

[consideRatio]

@ktaletsk for jupyterhub-idle-culler specifically, see https://github.com/jupyterhub/jupyterhub-idle-culler#permissions and note that if you are working with a distribution of jupyterhub like z2jh or tljh, that should be setup automatically for you - and if not - we should fix it. I know it is setup automatically in z2jh at this point, but not yet released - will be for z2jh 2.0.0+.

[consideRatio]

Action point

This issue can be resolved by updating this example to not reference an undefined scope like admin:services.

@consideRatio thanks for clarification. If the scope does not exist, we should update the documentation here:

https://github.com/jupyterhub/jupyterhub/blob/2dc2c99b4a8965e5526e37e8bff35842e937a838/docs/source/reference/rest.md?plain=1#L110-L123

[ktaletsk]

@consideRatio speaking of idle-culler, I also noticed the duplicated and inconsistent docs for cull-idle configs:

1. Get Started -> External Services https://github.com/jupyterhub/jupyterhub/blob/f6230001bbc25bf4d9543b124ac2fb4a01c9b1a2/docs/source/getting-started/services-basics.md?plain=1#L93-L113
2. JupyterHub RBAC -> Use Cases https://github.com/jupyterhub/jupyterhub/blob/f6230001bbc25bf4d9543b124ac2fb4a01c9b1a2/docs/source/rbac/use-cases.md?plain=1#L26-L44
3. JupyterHub API -> Services

   {
   'name': 'cull-idle',
   'command': ['python', '/path/to/cull-idle']
   'admin': True,
   }

Maybe unifying the docs for cull-idle and services in general could be useful?

[consideRatio]

@ktaletsk thanks for your work and summary of the situation! I opened https://github.com/jupyterhub/jupyterhub/issues/3814 to represent what you observed!