Add simple dropdown menu for selecting a network addon #2389

errordeveloper · 2017-01-31T16:04:58Z

This is to improve UX, it removes the need for users to click away to addon pages.

This a very simple version and only 3 addons are included right now, happy to extend this, if folks like the idea.

@lukemarsden @thockin @mikedanese @caseydavenport PTAL

Initial appearance:

Drop down choices:

Weave Net addon selected from dropdown:

This change is

thockin · 2017-02-01T06:58:05Z

This is cute. I'll leave it to Devin to decide if we want to support code in these docs.

errordeveloper · 2017-02-01T08:50:35Z

IMO we could do a similar thing for package installation instructions.

lukemarsden · 2017-02-01T15:04:43Z

Thanks @thockin! Hi @devin-donnelly - the context here is that we've had lots of users show up in SIG-cluster-lifecycle complaining that it's hard to find the instructions to install a network. At the same time, we also want to remain vendor neutral. This solution fixes the problem by showing users how to install a network inline in the setup guide, while remaining vendor neutral by making it clear that a choice is necessary at this stage. WDYT?

Regards maintaining the JS, sign us up ;)

thockin · 2017-02-01T16:48:50Z

One concern is that our docs should not really be a clearinghouse for every integration for every vendor. I am fine with this change, per second, but I worry about encouraging an ever-increasing list of instructions, especially for cases where the instructions are more than a one-liner.

…

On Feb 1, 2017 7:04 AM, "lukemarsden" ***@***.***> wrote: Thanks @thockin <https://github.com/thockin>! Hi @devin-donnelly <https://github.com/devin-donnelly> - the context here is that we've had lots of users show up in SIG-cluster-lifecycle complaining that it's hard to find the instructions to install a network. At the same time, we also want to remain vendor neutral. This solution fixes the problem by showing users how to install a network inline in the setup guide, while remaining vendor neutral by making it clear that a choice is necessary at this stage. WDYT? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2389 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVIbcz6rD1UkqUSZVXwh-H-9UiVEFks5rYJ8MgaJpZM4Ly0xO> .

luxas

We should let Canal and Romana join the party as well

luxas · 2017-02-01T16:50:30Z

docs/getting-started-guides/kubeadm.md

+<script>
+  var networkAddons = {
+    "Calico": "kubectl apply -f \"http://docs.projectcalico.org/v2.0/getting-started/kubernetes/installation/hosted/calico.yaml\"",
+    "Flannel": "kubeclt apply -f \"https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml?raw=true\"",


luxas · 2017-02-01T16:52:02Z

docs/getting-started-guides/kubeadm.md

+
+<p>
+  <select id="pickNetworkAddon" style="margin:1em;font-size:1.2em;">
+    <option>Please select a network addon...</option>


In case the user chooses this, I think the command should go back to # kubectl apply -f <selected-add-on.yaml>, now it does not

Yes, makes sense, will update.

caseydavenport

Still reluctant about adding more enumerations of (network) add-ons in numerous places in the k8s docs but I suppose this is OK.

caseydavenport · 2017-01-31T17:44:28Z

docs/getting-started-guides/kubeadm.md

+
+<script>
+  var networkAddons = {
+    "Calico": "kubectl apply -f \"http://docs.projectcalico.org/v2.0/getting-started/kubernetes/installation/hosted/calico.yaml\"",


The Calico add-on should be from this link: http://docs.projectcalico.org/v2.0/getting-started/kubernetes/installation/hosted/kubeadm/calico.yaml

URL looks the same to me...

Ah, I can see the kubeadm path segment...

@caseydavenport I think we should try to avoid having a version number in the URL. Can we have a "latest" or similar that corresponds to the latest stable release?

I've update the URL to a kubeadm specific one.

caseydavenport · 2017-02-01T16:53:48Z

docs/getting-started-guides/kubeadm.md

-    # kubectl apply -f <add-on.yaml>
+Several projects provide Kubernetes pod networks using CNI, some of which also support [Network Policy](/docs/user-guide/networkpolicies/).
+
+You must select a network addon from the drop-down menu below, and correct instructions will appear below.


This sort of implies that the add-on needs to be from the dropdown. We should make it clear that this is just a sampling of network add-ons and not the definitive list.

Makes sense, could you suggest a way to phrase it?

A specific suggestion would be very appreciated!

How about something like this:

"The dropdown below includes some common network add-ons. Select one from the dropdown to view its installation instructions."

Sorry to be late to this thread. I'm not a fan of this drop down idea. Mainly because I can't' recall ever seeing it used in docs to address this kind of problem? It seems like a strange thing to see on a doc page. Are there examples of this that someone could point me to?

Also, it doesn't address the problem of enumerating all the options because every add-on provider will want to be include in the drop down. Finally, it introduces additional doc edit/management complexity. So, in addition to markdown, I have to know javascript to make a change? Some of my trivially simple markdown edits have broken the rendering of some pages, and IMO adding scripts is opening a real bag of worms.

That said, happy to defer to doc experts on this.

Hey @chrismarino, I don't think it matters whether it's used in other docs, as long as it's obvious enough to users. IMHO, it's a very common GUI idiom to have a dropdown select which thing you're looking at. An alternative design could be tabs. But I don't think it makes much of a difference (and dropdown is more scalable than tabs).

I think what really does matter is that users are having a bad time:

So I understand that I need to complete Step 3 first, but I am totally lost on what to do for the network.I feel, this step is quite vague.

Hopefully it's fairly clear how the JS mapping works. Failing that, we have volunteered to maintain the JS.

errordeveloper · 2017-02-08T19:40:24Z

We should let Canal and Romana join the party as well

Yes, who should we ping?

luxas · 2017-02-08T19:47:28Z

cc @chrismarino for Romana
cc @lxpollitt for Canal

Also cc @tomdee

lukemarsden · 2017-02-10T08:59:15Z

Let's get this in, it dramatically improves the UX for the kubeadm guide! cc @devin-donnelly

errordeveloper · 2017-02-10T10:27:00Z

I've addressed the comments above.

lukemarsden · 2017-02-13T10:44:48Z

Hey @thockin, totally hear you. We keep getting feedback that the current guide isn't working for people, though. Users are having a bad time. This PR is a big step towards fixing that. Can you help us get this merged?

- add simple dropdown menu for selecting a network addon, so users don't have go to other pages to find the commands they need to run - remove unecessary information from the paragraph

errordeveloper · 2017-02-13T12:07:40Z

@caseydavenport I've used the text you've suggested, thanks very much.

@thockin @lukemarsden I've also edited the paragraph a bit more, there was some info in bold that was just unnecessary for anyone to know at that stage.

lukemarsden · 2017-02-13T14:23:53Z

Thanks @errordeveloper, LGTM

Added Romana to drop down

thockin · 2017-02-13T18:48:39Z

This is squarely in the domain of docs owners, who have an actual docs plan...

@devin-donnelly

Added Romana to drop down...

devin-donnelly · 2017-02-28T23:22:56Z

Sorry it's taken me so long to get in on this.

@errordeveloper , @lukemarsden : I'm not a big fan of dropping a new script into the documentation and then having to maintain it. I understand the reasoning behind this from a UX perspective, though.

As a compromise, have you considered using the Tabs functionality that's already installed on the site?

See this file: https://github.com/kubernetes/kubernetes.github.io/blob/master/_includes/tabs.html

These display different included code files in tabs rather than drop-downs, but it has the advantage of already being installed and working on the site and also lives in our _includes directory.

devin-donnelly · 2017-02-28T23:45:18Z

See this file for an example: kubernetes.github.io/docs/user-guide/services/operations.md

errordeveloper · 2017-03-01T07:01:29Z

@devin-donnelly I've only noticed tabs after I wrote this, I will try to use tabs for this, thanks.

chenopis · 2017-03-02T19:02:35Z

@errordeveloper I will close this PR for now then.

errordeveloper · 2017-03-03T08:32:06Z

@devin-donnelly I am afraid _include/tabs.html doesn't cut it for this purpose because:

it requires me to specify a file for which it wants to generate a link
- this makes sense with the common use-case, but doesn't make sense for commands
there's a way to have no default choice, which is what's required here
spaces in tab titles break it completely
- I have to say "WeaveNet" instead of "Weave Net"
- I cannot say "Please select one to the left" in the title of the first tab

More broadly, I've not been able to make meaningful UX out of it. I spent half-a-day yesterday.

We can try extending tabs, but the way that it's written right now makes my brain hurt. I've quite quickly written a simple Jekyll plugin that takes a JSON description of all command variants we want to put in separate tabs, but it turns out we cannot use plugins due to gh-pages gem, and @pwittrock confirmed the site is hosted on Github pages, so we cannot simply get rid of that gem. It would be really great if we could convert this page to use tabs for Debian/RedHat installation instructions also, let's figure it out.

lukemarsden · 2017-03-06T11:37:32Z

@chenopis Please re-open.

@devin-donnelly Please note Ilya's comments above. We tried the tabs route, and it turned out to be more complicated than what we were initially suggesting here. Additionally, the dropdown list is:

More scalable, as there's no horizontal width limit to the number of networks that can be featured.
More natural to have an "unselected default", which is necessary to avoid biasing towards one vendor.

chenopis · 2017-03-06T18:19:13Z

Ok, I'm reopening this for further discussion.

GheRivero · 2017-03-14T21:26:55Z

docs/getting-started-guides/kubeadm.md

+<script>
+  var networkAddons = {
+    "Calico": "kubectl apply -f \"http://docs.projectcalico.org/v2.0/getting-started/kubernetes/installation/hosted/kubeadm/calico.yaml\"",
+    "Flannel": "kubectl apply -f \"https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml?raw=true\"",


Flannel also needs to apply a RBAC file to run properly: https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel-rbac.yml
Would be helpful to have a single file a no external commands.

errordeveloper · 2017-03-15T00:37:15Z

Please make a PR to my branch.

…

On Tue, 14 Mar 2017, 21:26 Ghe Rivero, ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/getting-started-guides/kubeadm.md <#2389 (comment)> : > - - # kubectl apply -f <add-on.yaml> +You must install a pod network add-on so that your pods can communicate with each other, a cluster without a network add-on should not be considered fully-functional. + +**It is necessary to do this before you try to deploy any applications to your cluster.** + + +Several projects provide Kubernetes pod networks using CNI, some of which also support [Network Policy](/docs/user-guide/networkpolicies/). +The dropdown below includes some common network add-ons. Select one from the dropdown to view its installation instructions. + +See the [add-ons page](/docs/admin/addons/) to learn more about each of the available network add-ons. + +<script> + var networkAddons = { + "Calico": "kubectl apply -f \"http://docs.projectcalico.org/v2.0/getting-started/kubernetes/installation/hosted/kubeadm/calico.yaml\"", + "Flannel": "kubectl apply -f \"https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml?raw=true\"", Flannel also needs to apply a RBAC file to run properly: https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel-rbac.yml Would be helpful to have a single file a no external commands. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2389 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPWS7beYbUyULwJtVEbgaUbA3JbHqC8ks5rlwYhgaJpZM4Ly0xO> .

jaredbhatti · 2017-03-24T16:22:24Z

Per @thockin and @devin-donnelly concerns, I am strongly against this PR. I ask that you reconsider using tabs. The drop-down is difficult to read and distinguish from the text, and I'm EXTREMELY reluctant to support new UX that has near-similar functionality to something we already have on the site.

chenopis · 2017-03-28T20:29:36Z

FYI, we're going to discuss this at the next SIG Docs meeting on 4/4, tentatively scheduled for 10:30 am PDT:

Join from PC, Mac, Linux, iOS or Android: https://zoom.us/j/678394311
Or iPhone one-tap (US Toll): +16465588656,678394311# or +14086380968,678394311#

Or Telephone:
Dial: +1 646 558 8656 (US Toll) or +1 408 638 0968 (US Toll)
Meeting ID: 678 394 311
International numbers available: https://zoom.us/zoomconference?m=zy_s4GywCQIUgexWdq58vma1f9N8F8s8

chenopis · 2017-05-04T07:11:00Z

I have refactored the tabs implementation in PR #3268, and you can test it out here: https://deploy-preview-3268--kubernetes-io-master-staging.netlify.com/docs/tabs-example/

alexellis · 2017-06-26T14:29:53Z

I write quite a few tutorials for Docker Swarm (new version) and I tried to get started with Kubernetes via kubeadm for the first time.. it was a complete fail. It seems like the docs are trying to be impartial but by doing so only give hints as to what is required to get flannel working.. In the end I had to rely on a Kubernetes expert to give me the answers.

It would be great if this could be improved.

It's not clear that the --pod-network-cidr=10.244.0.0/16 reference is meant for kubeadm init - you should show that on one line.
My provider - Ubuntu 16.04 on Packet didn't have proc config - this could be quite common, so you should mention it in the context of the flight checks
After applying the flannel script - nothing worked and I had to get help from someone else to find out how to apply the flannel RBAC script.

Even if trying to be impartial - this guide needs to leave you with a working system at the end and right now it just left me super confused and I'm not a newbie to orchestration.

Needed in addition:

kubectl create -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel-rbac.yml

Before / after:

kubectl create -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

luxas · 2017-06-26T14:42:48Z

Thanks a lot @alexellis for that write-up. I hope that comment can bring this thread to life...

So TL;DR; I agree with @alexellis, @lukemarsden and @errordeveloper and also think this would be a really nice feature to merge. Basically let the providers add themselves to this dropdown list. If the provider is lazy enough to not do it; well bad for them, but they are probably still listed in the addons page.

Of course we'll ping all people involved to notify them they can add supported solutions to this list.
Lately there have been a lot of churn in the community about the complexity of finding which solutions work, and I totally agree. I still want to be very clear regarding that whatever satisfies the CNI+Kubernetes integration will work for kubeadm as well and that kubeadm won't choose either of these solutions.

But making these visible in the docs will actually help us target the users we want to target -- people that set up Kubernetes for the very first time; people that want to kick the tires with Kubernetes. Sure, kubeadm fits a lot of other people like experienced hackers of k8s as well, but that person can in theory build whatever system he/she wants anyway.

I'm wondering how this kind of straightforward change could stall out like this.
If we have to use tabs to be consistent, let's use tabs. If that isn't a great fit for this use-case, let's use a dropdown. I'm agnostic of that CSS-kind of stuff, but I really care about the user.

I'm currently updating the kubeadm docs to reflect the v1.7 release (#4018), and I might just add this kind of functionality in a second PR and try to push for this again

ping @thockin @devin-donnelly @chenopis @errordeveloper @lukemarsden

chenopis · 2017-06-26T15:59:16Z

I think @errordeveloper just hasn't had time to get back to this PR yet. The implementation of tabs is good to go, and I used this PR to model the example: https://kubernetes.io/docs/tabs-example/

lukemarsden · 2017-07-03T13:34:14Z

I think @luxas is going to take a look at this, instead of @errordeveloper now – thanks!

luxas · 2017-07-03T14:20:33Z

I'll do that this week, yes

…

On 03 Jul 2017, at 16:34, lukemarsden ***@***.***> wrote: I think @luxas is going to take a look at this, instead of @errordeveloper now – thanks! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

luxas · 2017-07-05T14:29:41Z

Implemented by: #4274

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jan 31, 2017

errordeveloper changed the title ~~Add simple dropdown menu for selecting a network addon~~ [RFC (do not merge)] Add simple dropdown menu for selecting a network addon Jan 31, 2017

k8s-github-robot assigned luxas Jan 31, 2017

chenopis added the do-not-merge DEPRECATED. Indicates that a PR should not merge. Label can only be manually applied/removed. label Jan 31, 2017

thockin assigned devin-donnelly Feb 1, 2017

luxas reviewed Feb 1, 2017

View reviewed changes

caseydavenport suggested changes Feb 1, 2017

View reviewed changes

errordeveloper force-pushed the network-addon-dropdown branch from 7c9b8d6 to 4409b87 Compare February 10, 2017 10:26

errordeveloper changed the title ~~[RFC (do not merge)] Add simple dropdown menu for selecting a network addon~~ Add simple dropdown menu for selecting a network addon Feb 10, 2017

errordeveloper force-pushed the network-addon-dropdown branch 2 times, most recently from 9b86b86 to 673f66d Compare February 13, 2017 12:04

Improve network addon instructions

671e9fc

- add simple dropdown menu for selecting a network addon, so users don't have go to other pages to find the commands they need to run - remove unecessary information from the paragraph

errordeveloper force-pushed the network-addon-dropdown branch from 673f66d to 671e9fc Compare February 13, 2017 12:06

chrismarino added 2 commits February 13, 2017 07:21

Added Romana to drop down...

56e946a

Added Romana to drop down

Update kubeadm.md

251d61f

Merge pull request #2 from chrismarino/patch-2

baa3085

Added Romana to drop down...

chenopis closed this Mar 2, 2017

chenopis reopened this Mar 6, 2017

GheRivero reviewed Mar 14, 2017

View reviewed changes

chenopis self-assigned this May 4, 2017

chenopis added the Docs Review: Open Issues label May 4, 2017

chenopis removed the do-not-merge DEPRECATED. Indicates that a PR should not merge. Label can only be manually applied/removed. label May 30, 2017

chenopis added the keep-open label Jun 7, 2017

luxas removed their assignment Jun 19, 2017

luxas mentioned this pull request Jun 26, 2017

docs: Add a Documentation/kubernetes.md page flannel-io/flannel#758

Closed

luxas mentioned this pull request Jul 5, 2017

kubeadm: Make tabs with information how to install 3rd-party CNI network solutions #4274

Merged

luxas closed this Jul 5, 2017

Add simple dropdown menu for selecting a network addon #2389

Add simple dropdown menu for selecting a network addon #2389

Uh oh!

Conversation

errordeveloper commented Jan 31, 2017 • edited by k8s-reviewable Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thockin commented Feb 1, 2017

Uh oh!

errordeveloper commented Feb 1, 2017

Uh oh!

lukemarsden commented Feb 1, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thockin commented Feb 1, 2017 via email

Uh oh!

luxas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

caseydavenport left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

errordeveloper commented Feb 8, 2017

Uh oh!

luxas commented Feb 8, 2017

Uh oh!

lukemarsden commented Feb 10, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

errordeveloper commented Feb 10, 2017

Uh oh!

lukemarsden commented Feb 13, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

errordeveloper commented Feb 13, 2017

Uh oh!

lukemarsden commented Feb 13, 2017

Uh oh!

thockin commented Feb 13, 2017

Uh oh!

devin-donnelly commented Feb 28, 2017

Uh oh!

devin-donnelly commented Feb 28, 2017

Uh oh!

errordeveloper commented Mar 1, 2017

Uh oh!

chenopis commented Mar 2, 2017

Uh oh!

errordeveloper commented Mar 3, 2017

Uh oh!

lukemarsden commented Mar 6, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

errordeveloper commented Jan 31, 2017 •

edited by k8s-reviewable

Loading

lukemarsden commented Feb 1, 2017 •

edited

Loading

lukemarsden commented Feb 10, 2017 •

edited

Loading

lukemarsden commented Feb 13, 2017 •

edited

Loading

lukemarsden commented Mar 6, 2017 •

edited

Loading

jaredbhatti commented Mar 24, 2017 •

edited

Loading