mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-18 15:33:02 +00:00
Merge pull request #1269 from willingc/network-docs
Streamline networking and using REST API Docs
This commit is contained in:
@@ -6,9 +6,9 @@ Configuration Reference
|
||||
|
||||
technical-overview
|
||||
websecurity
|
||||
rest
|
||||
authenticators
|
||||
spawners
|
||||
services
|
||||
rest
|
||||
upgrading
|
||||
config-examples
|
||||
|
@@ -51,10 +51,10 @@ Contents
|
||||
|
||||
* :doc:`technical-overview`
|
||||
* :doc:`websecurity`
|
||||
* :doc:`rest`
|
||||
* :doc:`authenticators`
|
||||
* :doc:`spawners`
|
||||
* :doc:`services`
|
||||
* :doc:`rest`
|
||||
* :doc:`upgrading`
|
||||
* :doc:`config-examples`
|
||||
|
||||
|
@@ -1,39 +1,59 @@
|
||||
# Networking basics
|
||||
|
||||
## Configuring the Proxy's IP address and port
|
||||
This section will help you with basic proxy and network configuration to:
|
||||
|
||||
- set the proxy's IP address and port
|
||||
- set the proxy's REST API URL
|
||||
- configure the Hub if the Proxy or Spawners are remote or isolated
|
||||
- set the `hub_connect_ip` which services will use to communicate with the hub
|
||||
|
||||
## Set the Proxy's IP address and port
|
||||
|
||||
The Proxy's main IP address setting determines where JupyterHub is available to users.
|
||||
By default, JupyterHub is configured to be available on all network interfaces
|
||||
(`''`) on port 8000. **Note**: Use of `'*'` is discouraged for IP configuration;
|
||||
(`''`) on port 8000. *Note*: Use of `'*'` is discouraged for IP configuration;
|
||||
instead, use of `'0.0.0.0'` is preferred.
|
||||
|
||||
Changing the IP address and port can be done with the following command line
|
||||
arguments:
|
||||
Changing the Proxy's main IP address and port can be done with the following
|
||||
JupyterHub **command line options**:
|
||||
|
||||
```bash
|
||||
jupyterhub --ip=192.168.1.2 --port=443
|
||||
```
|
||||
|
||||
Or by placing the following lines in a configuration file:
|
||||
Or by placing the following lines in a **configuration file**,
|
||||
`jupyterhub_config.py`:
|
||||
|
||||
```python
|
||||
c.JupyterHub.ip = '192.168.1.2'
|
||||
c.JupyterHub.port = 443
|
||||
```
|
||||
|
||||
Port 443 is used as an example since 443 is the default port for SSL/HTTPS.
|
||||
Port 443 is used in the examples since 443 is the default port for SSL/HTTPS.
|
||||
|
||||
Configuring only the main IP and port of JupyterHub should be sufficient for most deployments of JupyterHub.
|
||||
However, more customized scenarios may need additional networking details to
|
||||
be configured.
|
||||
Configuring only the main IP and port of JupyterHub should be sufficient for
|
||||
most deployments of JupyterHub. However, more customized scenarios may need
|
||||
additional networking details to be configured.
|
||||
|
||||
## Set the Proxy's REST API communication URL (optional)
|
||||
|
||||
## Configuring the Proxy's REST API communication IP address and port (optional)
|
||||
The Hub service talks to the proxy via a REST API on a secondary port,
|
||||
whose network interface and port can be configured separately.
|
||||
By default, this REST API listens on port 8081 of localhost only.
|
||||
By default, this REST API listens on port 8081 of `localhost` only.
|
||||
The Hub service talks to the proxy via a REST API on a secondary port. The
|
||||
API URL can be configured separately and override the default settings.
|
||||
|
||||
If running the Proxy separate from the Hub,
|
||||
configure the REST API communication IP address and port with:
|
||||
### Set api_url
|
||||
|
||||
The URL to access the API, `c.configurableHTTPProxy.api_url`, is configurable.
|
||||
An example entry to set the proxy's API URL in `jupyterhub_config.py` is:
|
||||
|
||||
```python
|
||||
c.ConfigurableHTTPProxy.api_url = 'http://10.0.1.4:5432'
|
||||
```
|
||||
|
||||
### proxy_api_ip and proxy_api_port (Deprecated in 0.8)
|
||||
|
||||
If running the Proxy separate from the Hub, configure the REST API communication
|
||||
IP address and port by adding this to the `jupyterhub_config.py` file:
|
||||
|
||||
```python
|
||||
# ideally a private network address
|
||||
@@ -41,10 +61,15 @@ c.JupyterHub.proxy_api_ip = '10.0.1.4'
|
||||
c.JupyterHub.proxy_api_port = 5432
|
||||
```
|
||||
|
||||
## Configuring the Hub if Spawners or Proxy are remote or isolated in containers
|
||||
The Hub service also listens only on localhost (port 8080) by default.
|
||||
The Hub needs needs to be accessible from both the proxy and all Spawners.
|
||||
When spawning local servers, an IP address setting of localhost is fine.
|
||||
We recommend using the proxy's `api_url` setting instead of the deprecated
|
||||
settings, `proxy_api_ip` and `proxy_api_port`.
|
||||
|
||||
## Configure the Hub if the Proxy or Spawners are remote or isolated
|
||||
|
||||
The Hub service listens only on `localhost` (port 8080) by default.
|
||||
The Hub needs to be accessible from both the proxy and all Spawners.
|
||||
When spawning local servers, an IP address setting of `localhost` is fine.
|
||||
|
||||
If *either* the Proxy *or* (more likely) the Spawners will be remote or
|
||||
isolated in containers, the Hub must listen on an IP that is accessible.
|
||||
|
||||
@@ -52,3 +77,12 @@ isolated in containers, the Hub must listen on an IP that is accessible.
|
||||
c.JupyterHub.hub_ip = '10.0.1.4'
|
||||
c.JupyterHub.hub_port = 54321
|
||||
```
|
||||
|
||||
**Added in 0.8:** The `c.JupyterHub.hub_connect_ip` setting is the ip address or
|
||||
hostname that other services should use to connect to the Hub. A common
|
||||
configuration for, e.g. docker, is:
|
||||
|
||||
```python
|
||||
c.JupyterHub.hub_ip = '0.0.0.0' # listen on all interfaces
|
||||
c.JupyterHub.hub_connect_ip = '10.0.1.4' # ip as seen on the docker network. Can also be a hostname.
|
||||
```
|
||||
|
@@ -1,5 +1,15 @@
|
||||
# Using JupyterHub's REST API
|
||||
|
||||
This section will give you information on:
|
||||
|
||||
- what you can do with the API
|
||||
- create an API token
|
||||
- add API tokens to the config files
|
||||
- make an API request programmatically using the requests library
|
||||
- learn more about JupyterHub's API
|
||||
|
||||
## What you can do with the API
|
||||
|
||||
Using the [JupyterHub REST API][], you can perform actions on the Hub,
|
||||
such as:
|
||||
|
||||
@@ -12,16 +22,16 @@ A [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)
|
||||
API provides a standard way for users to get and send information to the
|
||||
Hub.
|
||||
|
||||
## Create an API token
|
||||
|
||||
## Creating an API token
|
||||
To send requests using JupyterHub API, you must pass an API token with the
|
||||
request. You can create a token for an individual user using the following
|
||||
command:
|
||||
|
||||
jupyterhub token USERNAME
|
||||
|
||||
## Add API tokens to the config file
|
||||
|
||||
## Adding tokens to the config file
|
||||
You may also add a dictionary of API tokens and usernames to the hub's
|
||||
configuration file, `jupyterhub_config.py`:
|
||||
|
||||
@@ -31,16 +41,17 @@ c.JupyterHub.api_tokens = {
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Making an API request
|
||||
## Make an API request
|
||||
|
||||
To authenticate your requests, pass the API token in the request's
|
||||
Authorization header.
|
||||
|
||||
**Example: List the hub's users**
|
||||
### Use requests
|
||||
|
||||
Using the popular Python requests library, the following code sends an API
|
||||
request and an API token for authorization:
|
||||
Using the popular Python [requests](http://docs.python-requests.org/en/master/)
|
||||
library, here's example code to make an API request for the users of a JupyterHub
|
||||
deployment. An API GET request is made, and the request sends an API token for
|
||||
authorization. The response contains information about the users:
|
||||
|
||||
```python
|
||||
import requests
|
||||
@@ -57,18 +68,19 @@ r.raise_for_status()
|
||||
users = r.json()
|
||||
```
|
||||
|
||||
Note that the token authorizes JupyterHub REST API requests. The same token
|
||||
does **not** authorize access to the [Jupyter Notebook REST API][] provided
|
||||
by notebook servers managed by JupyterHub.
|
||||
Note that the API token authorizes **JupyterHub** REST API requests. The same
|
||||
token does **not** authorize access to the [Jupyter Notebook REST API][]
|
||||
provided by notebook servers managed by JupyterHub. A different token is used
|
||||
to access the **Jupyter Notebook** API.
|
||||
|
||||
## Learning more about the API
|
||||
## Learn more about the API
|
||||
|
||||
You can see the full [JupyterHub REST API][] for details.
|
||||
The same REST API Spec can be viewed in a more interactive style [on swagger's petstore][].
|
||||
You can see the full [JupyterHub REST API][] for details. This REST API Spec can
|
||||
be viewed in a more [interactive style on swagger's petstore][].
|
||||
Both resources contain the same information and differ only in its display.
|
||||
Note: The Swagger specification is being renamed the [OpenAPI Initiative][].
|
||||
|
||||
[on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default
|
||||
[interactive style on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default
|
||||
[OpenAPI Initiative]: https://www.openapis.org/
|
||||
[JupyterHub REST API]: ./_static/rest-api/index.html
|
||||
[Jupyter Notebook REST API]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml
|
||||
|
Reference in New Issue
Block a user