Restructured Getting Started Section #888

daniel-sanche · 2019-07-10T21:43:30Z

I was always a bit confused by the getting started section. This PR attempts to restructure it to group together different cloud and local deployment options, and removes some redundant files

old:

new:

This change is

k8s-ci-robot · 2019-07-10T21:43:36Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign aronchick
You can assign the PR to them by writing /assign @aronchick in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2019-07-10T21:43:43Z

Hi @dansanche. Thanks for your PR.

I'm waiting for a kubeflow member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

sarahmaddox · 2019-07-10T21:57:50Z

Fixes #889

/cc @mameshini What we talked about!

sarahmaddox · 2019-07-10T21:59:05Z

/assign @mameshini

sarahmaddox · 2019-07-10T21:59:56Z

/ok-to-test

daniel-sanche · 2019-07-11T16:05:42Z

Note that I removed the requirements.md and getting-started.md file, and tried to move the important information to the _index.md files instead. Let me know if that works

sarahmaddox · 2019-07-11T16:06:51Z

/unassign @mameshini
/assign @alecglassford

@alecglassford Please would you review this PR when it's ready?

k8s-ci-robot · 2019-07-11T16:06:52Z

@sarahmaddox: GitHub didn't allow me to assign the following users: alecglassford.

Note that only kubeflow members, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

/unassign @mameshini
/assign @alecglassford

@alecglassford Please would you review this PR when it's ready?

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

daniel-sanche · 2019-07-11T16:37:04Z

This should be ready to review now, thanks!

sarahmaddox · 2019-07-11T17:11:19Z

@dansanche It looks like someone has submitted a change to the file since you forked your branch. To fix, you need to merge in the changes and resolve any conflicts.

content/docs/started/On-Prem/_index.md

content/docs/started/Cloud/_index.md

content/docs/started/Local/_index.md

kbhawkey · 2019-07-11T19:36:01Z

content/docs/started/_index.md

+
+* [Kubernetes](https://kubernetes.io/docs/tutorials/kubernetes-basics/)
+* [TensorFlow](https://www.tensorflow.org/get_started/)
+* [ksonnet](https://ksonnet.io/docs/tutorial)


Is ksonnet still a requirement?

It's not, but I wanted to focus this PR on moving the existing docs around instead of making sure all the content in them is up to date. I believe there are some others working on removing ksonnet from the docs, and I don't want to duplicate their efforts

The removal of ksonnet from this page has already happened:
https://www.kubeflow.org/docs/started/requirements/
The above page is the source of the content that this PR moves to a different page. This is one of the reasons for the merge conflict that GitHub is reporting. Please would you do a careful sync and merge. :)

kbhawkey · 2019-07-11T19:37:42Z

content/docs/started/_index.md

+ * An existing Kubernetes cluster using Kubernetes version 
+   {{% kubernetes-min-version %}} or later:
+
+   * A minimum of 0.6 CPU in cluster (Reserved for 3 replicated ambassador pods and according to your need add additional CPUs)


Do these general requirements hold for most use cases?

Same as previous comment. I'm not sure, but I wanted to focus on restructuring existing content rather than verifying its accuracy

content/docs/started/getting-started-k8s.md

alecglassford

Generally LGTM!

Two nits:

You've named the new directories Cloud, Local, and On-Prem - why are these capitalized? It seems to be O.K. (they get rendered in lowercase in URLs), but I think giving them lowercase names would fit convention better. Unless there's a reason not to, can you change this?
Is the distinction between "local hardware" and "on-prem" clear to our audience? I understand that "local hardware" means, like, literally my laptop/development machine vs. "on-prem" means some sort of server/production-ready machine that I own—but at face value the terms sound kind of similar (?). I don't think you necessarily have to change them (and I don't have a good solution), but something to think about.

daniel-sanche · 2019-07-11T21:55:41Z

Good point, fixed
We had a lot of discussion about the best names for categories. We decided Local vs On-Prem because we wanted something short and descriptive, but I'm still open to other options. We could possibly change "On-Prem" to something like "Datacenters", but I'd say "On-Prem" is the more proper terminology, even if it can be confusing to those outside of that area.

I think we can try to clarify the differences better in the _index.md files

sarahmaddox · 2019-07-11T22:19:59Z

/assign

sarahmaddox · 2019-07-11T22:20:09Z

Preview: https://deploy-preview-888--competent-brattain-de2d6d.netlify.com/docs/started/

sarahmaddox · 2019-07-11T22:27:16Z

Note that I removed the requirements.md and getting-started.md file, and tried to move the important information to the _index.md files instead. Let me know if that works

Hallo @dansanche The second change (putting the info into the _index.md file) breaks the pattern that Docsy provides. For the sake of a consistent experience and ease of maintenance, let's keep the _index.md page as a generated list of links. The first page in the section (https://www.kubeflow.org/docs/started/getting-started/) then gives the primary getting-started instructions.

The first change (moving the content from the requirements page to the getting-started page) is a good one. I think we already have an issue for that move - you'll be able to mark that issue as fixed with this PR if you take that change on. (First check that no-one else is doing it already.)

Update: Here's the issue, and someone is already working on it: #845

sarahmaddox · 2019-07-11T22:27:51Z

/assign @alecglassford

k8s-ci-robot · 2019-07-11T22:27:52Z

@sarahmaddox: GitHub didn't allow me to assign the following users: alecglassford.

Note that only kubeflow members, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

/assign @alecglassford

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

carmine · 2019-07-12T19:00:20Z

I'm curious whether platform, as used in kfctl, is a better use? I find "local" and "on-prem" problematic - maybe "virtual" is better? The reason is that some of these solutions could work up in a public cloud, which wouldn't classify as local or on-prem.

carmine · 2019-07-12T19:09:14Z

content/docs/started/local/_index.md

+description = "Get started with Kubeflow on local hardware"
+weight = 1
+++
+


Should these be characterized as Local Virtual Machines?

carmine · 2019-07-12T19:11:26Z

content/docs/started/local/_index.md

+        minimal operating system and Kubernetes already installed.
+      * This option may be useful if you are just starting to learn and already
+	      have one of the virtualization applications installed.
+


microk8s will work on any linux system, local or in the cloud. Addtionally, with the advent of WSL2 on Windows, it'll work on Windows too. In the context of local, this will work without a virtual machine. I can make this edit afterwards or as part of this submission. Preference?

After discussing this with Sarah, I'm closing this PR for now. Please give your input on how best to restructure the Getting Started guide here: #889

daniel-sanche · 2019-07-12T19:40:36Z

Closing this and moving related discussion to the issue page

restructured Getting Started section

e8ee271

k8s-ci-robot requested review from Ark-kun and sarahmaddox July 10, 2019 21:43

k8s-ci-robot added the size/L label Jul 10, 2019

k8s-ci-robot added the needs-ok-to-test label Jul 10, 2019

k8s-ci-robot assigned mameshini Jul 10, 2019

k8s-ci-robot added ok-to-test and removed needs-ok-to-test labels Jul 10, 2019

daniel-sanche added 2 commits July 10, 2019 20:39

fixed broken links

d4688f2

created On-Prem section

bfcea67

k8s-ci-robot unassigned mameshini Jul 11, 2019

Merge branch 'master' into restructure-getting-started

4f042d4

kbhawkey reviewed Jul 11, 2019

View reviewed changes

content/docs/started/On-Prem/_index.md Outdated Show resolved Hide resolved

kbhawkey reviewed Jul 11, 2019

View reviewed changes

content/docs/started/Cloud/_index.md Outdated Show resolved Hide resolved

kbhawkey reviewed Jul 11, 2019

View reviewed changes

content/docs/started/Local/_index.md Outdated Show resolved Hide resolved

kbhawkey reviewed Jul 11, 2019

View reviewed changes

content/docs/started/getting-started-k8s.md Outdated Show resolved Hide resolved

alecglassford approved these changes Jul 11, 2019

View reviewed changes

daniel-sanche mentioned this pull request Jul 11, 2019

kubeflow on kubernetes: existing_arrikto: add instructions for connecting with LDAP/AD #898

Merged

daniel-sanche added 4 commits July 11, 2019 14:39

Kuberflow -> Kubeflow

75994d5

added period

0b102bc

renamed folders

2359590

removed caps for folders

9efa3b3

k8s-ci-robot assigned sarahmaddox Jul 11, 2019

carmine suggested changes Jul 12, 2019

View reviewed changes

daniel-sanche mentioned this pull request Jul 12, 2019

Refactor the Kubeflow getting-started section #889

Closed

daniel-sanche closed this Jul 12, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructured Getting Started Section #888

Restructured Getting Started Section #888

daniel-sanche commented Jul 10, 2019 •

edited by jlewi

Loading

k8s-ci-robot commented Jul 10, 2019

k8s-ci-robot commented Jul 10, 2019

sarahmaddox commented Jul 10, 2019

sarahmaddox commented Jul 10, 2019

sarahmaddox commented Jul 10, 2019

daniel-sanche commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019

k8s-ci-robot commented Jul 11, 2019

daniel-sanche commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019

kbhawkey Jul 11, 2019

daniel-sanche Jul 11, 2019

sarahmaddox Jul 11, 2019

kbhawkey Jul 11, 2019

daniel-sanche Jul 11, 2019

alecglassford left a comment

daniel-sanche commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019 •

edited

Loading

sarahmaddox commented Jul 11, 2019

k8s-ci-robot commented Jul 11, 2019

carmine commented Jul 12, 2019

carmine Jul 12, 2019

carmine Jul 12, 2019

daniel-sanche Jul 12, 2019

daniel-sanche commented Jul 12, 2019

Restructured Getting Started Section #888

Restructured Getting Started Section #888

Conversation

daniel-sanche commented Jul 10, 2019 • edited by jlewi Loading

k8s-ci-robot commented Jul 10, 2019

k8s-ci-robot commented Jul 10, 2019

sarahmaddox commented Jul 10, 2019

sarahmaddox commented Jul 10, 2019

sarahmaddox commented Jul 10, 2019

daniel-sanche commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019

k8s-ci-robot commented Jul 11, 2019

daniel-sanche commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alecglassford left a comment

Choose a reason for hiding this comment

daniel-sanche commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019

sarahmaddox commented Jul 11, 2019 • edited Loading

sarahmaddox commented Jul 11, 2019

k8s-ci-robot commented Jul 11, 2019

carmine commented Jul 12, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daniel-sanche commented Jul 12, 2019

daniel-sanche commented Jul 10, 2019 •

edited by jlewi

Loading

sarahmaddox commented Jul 11, 2019 •

edited

Loading