hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-18 07:23:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1269 from willingc/network-docs

Browse Source 
Streamline networking and using REST API Docs
This commit is contained in:
Carol Willing
2017-07-26 09:50:49 -07:00
committed by GitHub
parent 63d1c918e5 1b9cff6d5f
commit 128cf115a7
4 changed files with 81 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/configuration-guide.rst
View File

@@ -6,9 +6,9 @@ Configuration Reference
technical-overview
websecurity
rest
authenticators
spawners
services
rest
upgrading
config-examples

2
docs/source/index.rst
View File

@@ -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`

72
docs/source/networking-basics.md
View File

@@ -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.
```

40
docs/source/rest.md
View File

@@ -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