From c4d576260847d592b9a2d6a7735a614285e84d06 Mon Sep 17 00:00:00 2001 From: alwasega Date: Mon, 6 Feb 2023 11:31:37 +0300 Subject: [PATCH] Moved Explanation/Background files --- .../about}/contributor-list.md | 0 .../about}/gallery-jhub-deployments.md | 0 .../admin/capacity-planning.md | 6 +-- .../admin}/database.md | 4 +- .../{reference => background/admin}/oauth.md | 2 +- .../admin}/websecurity.md | 2 + docs/source/background/index.md | 37 +++++++++++++++++++ docs/source/changelog.md | 4 +- docs/source/contributing/security.md | 2 +- docs/source/contributing/setup.md | 2 +- docs/source/explanation/index.md | 8 ---- docs/source/index-about.md | 14 ------- docs/source/index-admin.md | 11 ------ docs/source/index.md | 24 +----------- docs/source/rbac/index.md | 2 +- docs/source/rbac/scopes.md | 6 ++- docs/source/rbac/tech-implementation.md | 4 +- docs/source/rbac/upgrade.md | 2 +- docs/source/rbac/use-cases.md | 4 +- docs/source/reference/index.md | 3 -- docs/source/reference/urls.md | 2 + 21 files changed, 63 insertions(+), 76 deletions(-) rename docs/source/{ => background/about}/contributor-list.md (100%) rename docs/source/{ => background/about}/gallery-jhub-deployments.md (100%) rename docs/source/{ => background}/admin/capacity-planning.md (99%) rename docs/source/{reference => background/admin}/database.md (98%) rename docs/source/{reference => background/admin}/oauth.md (99%) rename docs/source/{reference => background/admin}/websecurity.md (99%) create mode 100644 docs/source/background/index.md delete mode 100644 docs/source/explanation/index.md delete mode 100644 docs/source/index-about.md delete mode 100644 docs/source/index-admin.md diff --git a/docs/source/contributor-list.md b/docs/source/background/about/contributor-list.md similarity index 100% rename from docs/source/contributor-list.md rename to docs/source/background/about/contributor-list.md diff --git a/docs/source/gallery-jhub-deployments.md b/docs/source/background/about/gallery-jhub-deployments.md similarity index 100% rename from docs/source/gallery-jhub-deployments.md rename to docs/source/background/about/gallery-jhub-deployments.md diff --git a/docs/source/admin/capacity-planning.md b/docs/source/background/admin/capacity-planning.md similarity index 99% rename from docs/source/admin/capacity-planning.md rename to docs/source/background/admin/capacity-planning.md index ef0524cd..4b122b1b 100644 --- a/docs/source/admin/capacity-planning.md +++ b/docs/source/background/admin/capacity-planning.md @@ -40,7 +40,7 @@ The rest is going to be up to your users. Per-user overhead from JupyterHub is typically negligible up to at least a few hundred concurrent active users. -```{figure} ../images/mybinder-hub-components-cpu-memory.png +```{figure} /images/mybinder-hub-components-cpu-memory.png JupyterHub component resource usage for mybinder.org. ``` @@ -200,7 +200,7 @@ The limit here is actually Kubernetes' pods per node, not memory _or_ CPU. This is likely a extreme case, as many Binder users come from clicking links on webpages without any actual intention of running code. -```{figure} ../images/mybinder-load5.png +```{figure} /images/mybinder-load5.png mybinder.org node CPU usage is low with 50-150 users sharing just 8 cores ``` @@ -277,7 +277,7 @@ showing >90% of users using less than 10% CPU and 200MB, but a few outliers near the limit of 1 CPU and 2GB of RAM. This is the kind of information you can use to tune your requests and limits. -![Snapshot from JupyterHub's Grafana dashboards on mybinder.org](../images/mybinder-user-resources.png) +![Snapshot from JupyterHub's Grafana dashboards on mybinder.org](/images/mybinder-user-resources.png) [prometheus]: https://prometheus.io [grafana]: https://grafana.com diff --git a/docs/source/reference/database.md b/docs/source/background/admin/database.md similarity index 98% rename from docs/source/reference/database.md rename to docs/source/background/admin/database.md index edc26056..c3272503 100644 --- a/docs/source/reference/database.md +++ b/docs/source/background/admin/database.md @@ -1,3 +1,5 @@ +(hub-database)= + # The Hub's Database JupyterHub uses a database to store information about users, services, and other data needed for operating the Hub. @@ -80,7 +82,7 @@ Additionally, there is usually _very_ little load on the database itself. By far the most taxing activity on the database is the 'list all users' endpoint, primarily used by the [idle-culling service](https://github.com/jupyterhub/jupyterhub-idle-culler). Database-based optimizations have been added to make even these operations feasible for large numbers of users: -1. State filtering on [GET /users](./rest-api.md) with `?state=active`, +1. State filtering on [GET /users](jupyterhub-rest-API) with `?state=active`, which limits the number of results in the query to only the relevant subset (added in JupyterHub 1.3), rather than all users. 2. [Pagination](api-pagination) of all list endpoints, allowing the request of a large number of resources to be more fairly balanced with other Hub activities across multiple requests (added in 2.0). diff --git a/docs/source/reference/oauth.md b/docs/source/background/admin/oauth.md similarity index 99% rename from docs/source/reference/oauth.md rename to docs/source/background/admin/oauth.md index ab0aeb86..edc2aea6 100644 --- a/docs/source/reference/oauth.md +++ b/docs/source/background/admin/oauth.md @@ -255,7 +255,7 @@ To authenticate this request, the single token stored in the encrypted cookie is If the user model matches who should be allowed (e.g. Danez), then the request is allowed. -See {doc}`../rbac/scopes` for how JupyterHub uses scopes to determine authorized access to servers and services. +See [Scopes in JupyterHub](jupyterhub-scopes) for how JupyterHub uses scopes to determine authorized access to servers and services. _the end_ diff --git a/docs/source/reference/websecurity.md b/docs/source/background/admin/websecurity.md similarity index 99% rename from docs/source/reference/websecurity.md rename to docs/source/background/admin/websecurity.md index 8ff2cc23..d4970187 100644 --- a/docs/source/reference/websecurity.md +++ b/docs/source/background/admin/websecurity.md @@ -1,3 +1,5 @@ +(web-security)= + # Security Overview The **Security Overview** section helps you learn about: diff --git a/docs/source/background/index.md b/docs/source/background/index.md new file mode 100644 index 00000000..3a446aab --- /dev/null +++ b/docs/source/background/index.md @@ -0,0 +1,37 @@ +# Background + +_Background_ provides some basic information about JupyterHub and big-picture illustrations of how it works. This section is meant to build your understanding of particular topics and JupyterHub in general. + +## About JupyterHub +JupyterHub is an open source project and community. It is a part of the +[Jupyter Project](https://jupyter.org). This section covers information +about our community as well as institutions that are presently using JupyterHub. + +```{toctree} +:maxdepth: 1 + +about/gallery-jhub-deployments +../changelog +about/contributor-list +``` + +## Administration +This section provides information relevant to running your own JupyterHub over time. + +```{toctree} +:maxdepth: 1 + +admin/capacity-planning +admin/database +admin/websecurity +admin/oauth +``` + +## JupyterHub RBAC +This section covers how Role Based Access Control (RBAC) is implemented in JupyterHub to control access to Jupyterhub's API resources. + +```{toctree} +:maxdepth: 2 + +../rbac/index +``` \ No newline at end of file diff --git a/docs/source/changelog.md b/docs/source/changelog.md index 523a6b77..4c1a8191 100644 --- a/docs/source/changelog.md +++ b/docs/source/changelog.md @@ -207,7 +207,7 @@ More info in {ref}`available-scopes-target`. - The admin UI can now show more detailed info about users and their servers in a drop-down details table: - ![Details view in admin UI](./images/dropdown-details-3.0.png) + ![Details view in admin UI](/images/dropdown-details-3.0.png) - Several bugfixes and improvements in the new admin UI. - Direct access to the Hub's database is deprecated. @@ -1355,7 +1355,7 @@ whether it was through discussion, testing, documentation, or development. - There is now full UI support for managing named servers. With named servers, each jupyterhub user may have access to more than one named server. For example, a professor may access a server named `research` and another named `teaching`. - ![named servers on the home page](./images/named-servers-home.png) + ![named servers on the home page](/images/named-servers-home.png) - Authenticators can now expire and refresh authentication data by implementing `Authenticator.refresh_user(user)`. diff --git a/docs/source/contributing/security.md b/docs/source/contributing/security.md index 0589c65d..66dc294d 100644 --- a/docs/source/contributing/security.md +++ b/docs/source/contributing/security.md @@ -1,7 +1,7 @@ # Reporting security issues in Jupyter or JupyterHub If you find a security vulnerability in Jupyter or JupyterHub, -whether it is a failure of the security model described in {doc}`../reference/websecurity` +whether it is a failure of the security model described in [Security Overview](web-security) or a failure in implementation, please report it to . diff --git a/docs/source/contributing/setup.md b/docs/source/contributing/setup.md index 0bde832f..def3bc24 100644 --- a/docs/source/contributing/setup.md +++ b/docs/source/contributing/setup.md @@ -103,7 +103,7 @@ a more detailed discussion. The default database engine is `sqlite` so if you are just trying to get up and running quickly for local development that should be available via [Python](https://docs.python.org/3.5/library/sqlite3.html). - See {doc}`/reference/database` for details on other supported databases. + See [The Hub's Database](hub-database) for details on other supported databases. 6. You are now ready to start JupyterHub! diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md deleted file mode 100644 index 07dbcc86..00000000 --- a/docs/source/explanation/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Explanation - -The explanation guides are written to provide big-picture explanations of how JupyterHub works. They are meant to build your understanding of particular topics. - -```{toctree} -:maxdepth: 2 - -``` diff --git a/docs/source/index-about.md b/docs/source/index-about.md deleted file mode 100644 index 9372c4e7..00000000 --- a/docs/source/index-about.md +++ /dev/null @@ -1,14 +0,0 @@ -# About - -JupyterHub is an open source project and community. It is a part of the -[Jupyter Project](https://jupyter.org). JupyterHub is an open and inclusive -community, and invites contributions from anyone. This section covers information -about our community, as well as ways that you can connect and get involved. - -```{toctree} -:maxdepth: 1 - -contributor-list -changelog -gallery-jhub-deployments -``` diff --git a/docs/source/index-admin.md b/docs/source/index-admin.md deleted file mode 100644 index 05e2bfe1..00000000 --- a/docs/source/index-admin.md +++ /dev/null @@ -1,11 +0,0 @@ -# Administrator's Guide - -This guide covers best-practices, tips, common questions and operations, as -well as other information relevant to running your own JupyterHub over time. - -```{toctree} -:maxdepth: 2 - -admin/capacity-planning -changelog -``` diff --git a/docs/source/index.md b/docs/source/index.md index 83be428e..123da5dc 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -55,8 +55,8 @@ Documentation sections (reorganization in-progress) tutorial/index.md howto/index.md -explanation/index.md reference/index.md +background/index.md faq/index.md ``` @@ -89,14 +89,6 @@ configuration of JupyterHub_. reference/index ``` -### Administrators guide - -```{toctree} -:maxdepth: 2 - -index-admin -``` - ### API Reference ```{toctree} @@ -105,13 +97,6 @@ index-admin api/index ``` -### RBAC Reference - -```{toctree} -:maxdepth: 2 - -rbac/index -``` ### Contributing @@ -128,13 +113,6 @@ help keep our community welcoming to as many people as possible. contributing/index ``` -### About JupyterHub - -```{toctree} -:maxdepth: 2 - -index-about -``` ## Indices and tables diff --git a/docs/source/rbac/index.md b/docs/source/rbac/index.md index 3be61c54..e7030baf 100644 --- a/docs/source/rbac/index.md +++ b/docs/source/rbac/index.md @@ -1,4 +1,4 @@ -(RBAC)= +(rbac)= # JupyterHub RBAC diff --git a/docs/source/rbac/scopes.md b/docs/source/rbac/scopes.md index 175b5fa5..f30c33f9 100644 --- a/docs/source/rbac/scopes.md +++ b/docs/source/rbac/scopes.md @@ -1,8 +1,10 @@ +(jupyterhub-scopes)= + # Scopes in JupyterHub A scope has a syntax-based design that reveals which resources it provides access to. Resources are objects with a type, associated data, relationships to other resources, and a set of methods that operate on them (see [RESTful API](https://restful-api-design.readthedocs.io/en/latest/resources.html) documentation for more information). -`` in the RBAC scope design refers to the resource name in the [JupyterHub's API](../reference/rest-api.md) endpoints in most cases. For instance, `` equal to `users` corresponds to JupyterHub's API endpoints beginning with _/users_. +`` in the RBAC scope design refers to the resource name in the [JupyterHub's API](jupyterhub-rest-API) endpoints in most cases. For instance, `` equal to `users` corresponds to JupyterHub's API endpoints beginning with _/users_. (scope-conventions-target)= @@ -298,6 +300,6 @@ Custom scope _filters_ are NOT supported. ### Scopes and APIs -The scopes are also listed in the [](../reference/rest-api.md) documentation. Each API endpoint has a list of scopes which can be used to access the API; if no scopes are listed, the API is not authenticated and can be accessed without any permissions (i.e., no scopes). +The scopes are also listed in the [](jupyterhub-rest-API) documentation. Each API endpoint has a list of scopes which can be used to access the API; if no scopes are listed, the API is not authenticated and can be accessed without any permissions (i.e., no scopes). Listed scopes by each API endpoint reflect the "lowest" permissions required to gain any access to the corresponding API. For example, posting user's activity (_POST /users/:name/activity_) needs `users:activity` scope. If scope `users` is passed during the request, the access will be granted as the required scope is a subscope of the `users` scope. If, on the other hand, `read:users:activity` scope is passed, the access will be denied. diff --git a/docs/source/rbac/tech-implementation.md b/docs/source/rbac/tech-implementation.md index bc765020..7cc1dc66 100644 --- a/docs/source/rbac/tech-implementation.md +++ b/docs/source/rbac/tech-implementation.md @@ -65,7 +65,7 @@ If the token's scopes are a subset of the token owner's scopes, the token is iss {ref}`Figure 1 ` below illustrates the steps involved. The orange rectangles highlight where in the process the roles and scopes are resolved. -```{figure} ../images/rbac-token-request-chart.png +```{figure} /images/rbac-token-request-chart.png :align: center :name: token-request-chart @@ -91,7 +91,7 @@ The passed scopes are compared to the scopes required to access the API as follo {ref}`Figure 2 ` illustrates this process highlighting the steps where the role and scope resolutions as well as filtering occur in orange. -```{figure} ../images/rbac-api-request-chart.png +```{figure} /images/rbac-api-request-chart.png :align: center :name: api-request-chart diff --git a/docs/source/rbac/upgrade.md b/docs/source/rbac/upgrade.md index c6f85717..22f017bd 100644 --- a/docs/source/rbac/upgrade.md +++ b/docs/source/rbac/upgrade.md @@ -45,7 +45,7 @@ OAuth token is issued by the Hub to a single-user server when the user logs in. API token is issued by the Hub to a single-user server when launched and is used to communicate with the Hub's APIs such as posting activity or completing the OAuth flow. This token has no expiry by default. -API tokens can also be issued to users via API ([_/hub/token_](../reference/urls.md) or [_POST /users/:username/tokens_](../reference/rest-api.md)) and services via `jupyterhub_config.py` to perform API requests. +API tokens can also be issued to users via API ([_/hub/token_](jupyterhub-url) or [_POST /users/:username/tokens_](jupyterhub-rest-API)) and services via `jupyterhub_config.py` to perform API requests. ### With RBAC diff --git a/docs/source/rbac/use-cases.md b/docs/source/rbac/use-cases.md index d5877523..f13e6b75 100644 --- a/docs/source/rbac/use-cases.md +++ b/docs/source/rbac/use-cases.md @@ -3,13 +3,13 @@ To determine which scopes a role should have, one can follow these steps: 1. Determine what actions the role holder should have/have not access to -2. Match the actions against the [JupyterHub's APIs](../reference/rest-api.md) +2. Match the actions against the [JupyterHub's APIs](jupyterhub-rest-API) 3. Check which scopes are required to access the APIs 4. Combine scopes and subscopes if applicable 5. Customize the scopes with filters if needed 6. Define the role with required scopes and assign to users/services/groups/tokens -Below, different use cases are presented on how to use the [RBAC framework](./index.md) +Below, different use cases are presented on how to use the [RBAC framework](rbac) ## Service to cull idle servers diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md index 5a253089..cc14615b 100644 --- a/docs/source/reference/index.md +++ b/docs/source/reference/index.md @@ -10,14 +10,11 @@ what happens under-the-hood when you deploy and configure your JupyterHub. technical-overview urls -websecurity authenticators spawners services rest-api monitoring -database ../events/index config-reference -oauth ``` diff --git a/docs/source/reference/urls.md b/docs/source/reference/urls.md index c2ac95d5..61a92d75 100644 --- a/docs/source/reference/urls.md +++ b/docs/source/reference/urls.md @@ -1,3 +1,5 @@ +(jupyterhub-url)= + # JupyterHub URL scheme This document describes how JupyterHub routes requests.