From af36a2b2c2bf6437f2561b17ab5ca67b6bccd242 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Wed, 2 May 2018 15:11:52 -0700 Subject: [PATCH 1/2] miscellaneous doc updates take 2 --- doc/source/cost.rst | 13 +++++- doc/source/index.rst | 1 + doc/source/security.md | 20 +++++++++- doc/source/tips.rst | 70 +++++++++++++++++++++++++++++++++ doc/source/user-environment.rst | 2 +- 5 files changed, 101 insertions(+), 5 deletions(-) create mode 100644 doc/source/tips.rst diff --git a/doc/source/cost.rst b/doc/source/cost.rst index 325d697ac3..e324d8bca9 100644 --- a/doc/source/cost.rst +++ b/doc/source/cost.rst @@ -12,6 +12,15 @@ Appendix: Projecting deployment costs by our users. We **caution** that costs can vary widely based on providers selected and your use cases. +Cost calculators for cloud providers +------------------------------------ + +Below are several links to cost estimators for cloud providers: + +* `Google Cloud Platform cost calculator `_ +* `Amazon AWS cost calculator `_ +* `Microsoft Azure cost claculator `_ + Factors influencing costs ------------------------- @@ -59,8 +68,8 @@ auto-scaling functionality, but currently it does not. This means that you need to provision resources for the *maximum* expected number of users at one time. -Interactive Cost Estimator --------------------------- +Interactive Cost Estimator (rough estimate) +------------------------------------------- This small notebook may help you to make an initial planning estimate of costs for your JupyterHub instance. diff --git a/doc/source/index.rst b/doc/source/index.rst index a1ce7293da..62a5451103 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -133,6 +133,7 @@ Please submit a pull request to add to this section. Thanks. additional-resources users-list + tips .. _reference: diff --git a/doc/source/security.md b/doc/source/security.md index 599075a007..31ce4255f7 100644 --- a/doc/source/security.md +++ b/doc/source/security.md @@ -31,7 +31,13 @@ on HTTPS security see the certificates section of [this blog post](https://blog. ### Set up automatic HTTPS -1. Specify the two bits of information that we need to automatically provision HTTPS certificates - your domain name & a contact email address. +JupyterHub uses [Let's Encrypt](https://letsencrypt.org/) to automatically create +HTTPS certificates for your deployment. This will cause your HTTPS certificate +to automatically renew every few months. To enable this, make the following +changes to your `config.yaml` file: + +1. Specify the two bits of information that we need to automatically provision +HTTPS certificates - your domain name & a contact email address. ```yaml proxy: @@ -42,7 +48,7 @@ on HTTPS security see the certificates section of [this blog post](https://blog. contactEmail: ``` -2. Apply the config changes by running helm upgrade .... +2. Apply the config changes by running `helm upgrade ...` 3. Wait for about a minute, now your hub should be HTTPS enabled! ### Set up manual HTTPS @@ -71,6 +77,16 @@ If you have your own HTTPS certificates & want to use those instead of the autom 2. Apply the config changes by running helm upgrade .... 3. Wait for about a minute, now your hub should be HTTPS enabled! +### Confirm that your domain is running HTTPS + +There are many ways to confirm that a domain is running trusted HTTPS +certificates. One options is to use the [Qualys SSL Labs](https://ssllabs.com) +security report generator. Use the following URL structure to test your domain: + + ``` + http://ssllabs.com/ssltest/analyze.html?d= + ``` + ## Secure access to Helm In its default configuration, helm pretty much allows root access to all other diff --git a/doc/source/tips.rst b/doc/source/tips.rst new file mode 100644 index 0000000000..66c11fbbe7 --- /dev/null +++ b/doc/source/tips.rst @@ -0,0 +1,70 @@ +Tips and command snippets +========================= + +This is a page to collect a few particularly useful patterns and snippets +that help you interact with your Kubernetes cluster and JupyterHub. +If there's something that you think is generic enough (and not obvious enough) +to be added to this page, please feel free to make a PR! + +``kubectl`` autocompletion +-------------------------- + +Kubernetes has a helper script that allows you to auto-complete commands +and references to objects when using ``kubectl``. This lets you +````-complete and saves a lot of time. + +`Here are the instructions to install kubectl auto-completion `_. + +``helm`` autocompletion +----------------------- + +Helm also has an auto-completion script that lets you ````-complete +your commands when using Helm. + +`Here are the instructions to install helm auto-completion `_. + + +Managing ``kubectl`` contexts +----------------------------- + +Oftentimes people manage multiple Kubernetes deployments at the same time. +``kubectl`` handles this with the idea of "contexts", which specify which +kubernetes deployment you are referring to when you type ``kubectl get XXX``. + +To see a list of contexts currently available to you, use the following +command: + + kubectl config get-contexts + +This will list all of your Kubernetes contexts. You can select a particular +context by entering: + + kubectl config use-context + + +Specifying a default namespace for a context +-------------------------------------------- + +If you grow tired of typing ``namespace=XXX`` each time you type a kubernetes +command, here's a snippet that will allow you set a _default_ namespace for +a given Kubernetes context: + + kubectl config set-context $(kubectl config current-context) --namespace= + +The above command will only apply to the _currently active context_, and will +allow you to skip the ``--namespace=`` part of your commands for this context. + + +Using labels and selectors with ``kubectl`` +------------------------------------------- + +Sometimes it's useful to select an entire _class_ of Kubernetes objects rather +than referring to them by their name. You can attach an arbitrary set of +_labels_ to a Kubernetes object, and can then refer to those labels when +searching with ``kubectl``. + +To search based on a label value, use the ``-l`` or ``--label`` keyword +arguments. For example, JupyterHub creates a specific subset of labels for all +user pods. You can search for all user pods with the following label query: + + kubectl --namespace= get pod -l "component=singleuser-server" diff --git a/doc/source/user-environment.rst b/doc/source/user-environment.rst index 2b6bf15192..c8d5bbe33a 100644 --- a/doc/source/user-environment.rst +++ b/doc/source/user-environment.rst @@ -62,7 +62,7 @@ existing image, such as the ``scipy-notebook`` image, complete these steps: .. note:: - Container image name cannot be longer than 63 characters. + Container image names cannot be longer than 63 characters. Always use an explicit ``tag``, such as a specific commit. From 1b5744e02e57c828d059e27a5d7ef58415fc3be1 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 3 May 2018 09:26:39 -0700 Subject: [PATCH 2/2] erik suggestions --- doc/source/tips.rst | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/doc/source/tips.rst b/doc/source/tips.rst index 66c11fbbe7..44e5c081d4 100644 --- a/doc/source/tips.rst +++ b/doc/source/tips.rst @@ -63,8 +63,25 @@ than referring to them by their name. You can attach an arbitrary set of _labels_ to a Kubernetes object, and can then refer to those labels when searching with ``kubectl``. -To search based on a label value, use the ``-l`` or ``--label`` keyword +To search based on a label value, use the ``-l`` or ``--selector=`` keyword arguments. For example, JupyterHub creates a specific subset of labels for all user pods. You can search for all user pods with the following label query: kubectl --namespace= get pod -l "component=singleuser-server" + +For more information, see the `Kubernetes labels and selectors page `_. + +Asking for a more verbose or structured output +---------------------------------------------- + +Sometimes the information that's in the default output for ``kubectl get `` +is not enough for your needs, or isn't structured the way you'd like. We +recommend looking into the different kubernetes output options, which can be +modified like so: + + kubectl --namespace= get pod -o + +You can find more information on what kinds of output you can generate at +`the kubectl information page `_. +(click and search for the text "Output Options") +