Docs improvement | Step Zero: k8s on Azure docs

[sgibson91]

Hi everyone! I'm working through building a BinderHub and getting ready for the Turing Way BinderHub workshop (agenda here).

I've tried to capture in this issue some of the questions that I've had in working through the Step Zero: Kubernetes on Microsoft Azure Container Service (AKS) docs.

I'm a bit fuzzy on the boundary between what info you (binder) should provide and what should be "go and read up on k8s before trying this" - so feel free to ignore some of these if you don't feel they fall into your remit!

My general feeling is that these instructions are "type this and it works" (which is fine until it doesn't!) with a bit of explanation but not a lot...which left me feeling rather low on confidence that I knew what was going on!

Again though, this might be a case of "go and read up on this stuff before doing this tutorial" rather than filling in the blanks here! So an alternative answer to the suggestions that I've made below is to link out to other useful tutorials at these various points :smile_cat:

So without further ado...

Step 3

3. Create a Resource Group

az group create --name=<RESOURCE-GROUP-NAME> \
                --location=centralus \
                --output table

There's a link to other locations supported by AKS but the documentation doesn’t explain why it’s important (I think its for resource availability for example). I would have felt a little more secure with that information.

What do you think about changing centralus to <LOCATION> so the reader is forced to fill this in and think about the options too, rather than just copying?

Step 4

4. Choose a cluster name. In the following steps we’ll run commands that ask you to input a cluster name. We recommend using something descriptive and short. We’ll refer to this as <CLUSTER-NAME> for the remainder of this section. The next step will create a few files on your filesystem, so first create a folder in which these files will go. We recommend giving it the same name as your cluster:

mkdir <CLUSTER-NAME>
cd <CLUSTER-NAME>

When I got to this question I had the following questions:

• When/how often will this folder be accessed?
• Will I need this info when I'm customising/maintaining my JupyterHub/BinderHub or am I free to delete it once the k8s cluster is deployed?
• If I do need to keep it, where's a "sensible" place for the example use case of an IT team jointly maintaining a JupyterHub/BinderHub? (My Desktop is becoming cluttered with failed cluster folders!)

I think a little guidance around this would be nice.

Step 5

5. Create an ssh key to secure your cluster.

What am I securing the cluster against? Maybe a link to a recommended reading on web security would help new folks (like me :grimacing:)

Step 6

6. Create an AKS cluster. The following command will request a Kubernetes cluster within the resource group that we created earlier.

az aks create --name <CLUSTER-NAME> \
              --resource-group <RESOURCE-GROUP-NAME> \
              --ssh-key-value ssh-key-<CLUSTER-NAME>.pub \
              --node-count 3 \
              --node-vm-size Standard_D2s_v3 \
              --output table

Why do you specifically ask for --node-count 3 here? When I did this tutorial, it was on a "Free Trial" Azure subscription and this node count was above my allowed limit and I had to use --node-count 1 instead and I was nervous to change it as I'm not clear on what effect this change will have on my JupyterHub/BinderHub :cold_sweat:

Could we add a little extra documentation on the consequences of changing some of these values? What do you think?

Step 7

7. If you’re using the Azure CLI locally, install kubectl, a tool for accessing the Kubernetes API from the commandline: az aks install-cli

I got the following error from this line:

Downloading client to "/usr/local/bin/kubectl" from "https://storage.googleapis.com/kubernetes-release/release/v1.13.3/bin/darwin/amd64/kubectl"
Connection error while attempting to download client ([Errno 13] Permission denied: '/usr/local/bin/kubectl')

I used Homebrew to install kubernetes-cli (i.e. kubectl): brew install kubernetes-cli instead and it all worked. Is it important that the version of k8s installed on the cluster is now different to what I'm running locally?

If this occurs a lot, maybe we could move this step to before step 6 so that the reader knows which version they've been able to install to pass as the --kubernetes-version argument when creating the cluster?

For context: I was using a terminal rather than the Azure Cloud Shell as one goal of The Turing Way project is to develop a set of scripts to automatically deploy a BinderHub to Azure (much like nicain's module here).

THANK YOU

Just to re-iterate, I don't want you to think that I'm making you do all this extra documentation. I'm super happy to brainstorm different structures for where to link out to things. I'm sorry I don't know the answers to be able to put in a PR!!

I hope it's helpful to have the feedback though. And thank you so much for the help.

[consideRatio]

I'm on lunch break and must go back to work, but after reading half of this I just wanted to quickly stop and say THANK YOU @sgibson91 for providing such excellent concrete feedback on your experience following the guide! :heart:

[sgibson91]

Thank you @consideRatio, I have some other feedback on steps after this as well. I was going to go page by page to avoid creating one massive issue, if that sounds sensible?

[manics]

I think a lot of this applies to all public-cloud deployments, perhaps some of it could go into a step-minus-one intro page, with only the azure-specific docs here?

[sgibson91]

Hi @manics A cloud-neutral intro page sounds like a great idea!

[trallard]

Heya folks... this is something I can help with (and I would be willing to help with). Just give me a while (a few weeks) while I settle in and have more brain/time capacity to get something written down

[consideRatio]

@sgibson91 I'm issue triaging but figured I'll recruit you to help me with this issue! Action plans, small fixes, next steps?

[sgibson91]

• If I do need to keep it, where's a "sensible" place for the example use case of an IT team jointly maintaining a JupyterHub/BinderHub? (My Desktop is becoming cluttered with failed cluster folders!)

I think for this point, we could link out to resources like git-crypt/.gitignoring a secrets folder if the config will be kept in a version control repository. Or for a full Azure solution, link to Key Vault documentation for storing secrets and then Hub23's Azure Pipeline as an example of CI/CD? This needn't be more than an info box titled something like "Wondering where to store these things?"

I honestly think the majority of this issue could be resolved with a few statements like "To learn more about this, read this documentation <link>".