Merge pull request #672 from choldgraf/docs

miscellaneous doc updates take 2

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 <https://cloud.google.com/products/calculator/>`_
+* `Amazon AWS cost calculator <https://calculator.s3.amazonaws.com/index.html>`_
+* `Microsoft Azure cost claculator <https://azure.microsoft.com/en-us/pricing/calculator/>`_
+
 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.

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:
 

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: <your-email-address>
    ```
 
-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=<YOUR-DOMAIN>
+    ```
+
 ## Secure access to Helm
 
 In its default configuration, helm pretty much allows root access to all other

doc/source/tips.rst

@@ -0,0 +1,87 @@
+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
+``<TAB>``-complete and saves a lot of time.
+
+`Here are the instructions to install kubectl auto-completion <https://kubernetes.io/docs/tasks/tools/install-kubectl/#enabling-shell-autocompletion>`_.
+
+``helm`` autocompletion
+-----------------------
+
+Helm also has an auto-completion script that lets you ``<TAB>``-complete
+your commands when using Helm.
+
+`Here are the instructions to install helm auto-completion <https://docs.helm.sh/helm/#helm-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 <CONTEXT-NAME>
+
+
+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=<YOUR-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 ``--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=<YOUR-NAMESPACE> get pod -l "component=singleuser-server"
+
+For more information, see the `Kubernetes labels and selectors page <https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/>`_.
+
+Asking for a more verbose or structured output
+----------------------------------------------
+
+Sometimes the information that's in the default output for ``kubectl get <XXX>``
+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=<NAMESPACE> get pod -o <json|yaml|wide|name...>
+
+You can find more information on what kinds of output you can generate at
+`the kubectl information page <https://kubernetes.io/docs/reference/kubectl/overview/>`_.
+(click and search for the text "Output Options")
+

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.