Refactor the "Getting Started" "Installing Kubeflow" page

[thesuperzapper]

As we have been moving all distribution-specific docs out of "Getting Started" with PRs like #2576, #2577, #2569, #2492, we should now clean up the first place people look when trying to install Kubeflow.

As proposed by @cvenets here we should clearly indicate the two "paths" for installing Kubeflow:

1. Roll your own -- using the kubeflow/manifests yourself, with no support
2. Supported Distribution -- using a vendor or community supported install process

I think this leaves us with the following sections in "Getting Started" / "Installing Kubeflow":

## Overview
* discussion about Kubeflow being a "Kubernetes" app, with multiple components which can be mix-and-matched
* discussion about the two "paths" as described above, "Roll your own" and "Distribution"
* discussion about how Kubeflow is versioned, e.g. what 1.3, 1.4, even mean.

## Path 1: Roll Your Own
* Either take the content in the README of `kubeflow/manifests`, or just link to it
* https://github.com/kubeflow/manifests#kubeflow-manifests

## Path 2: Supported Distribution 

### Vendor Supported
a TABLE which lists the currently maintained VENDOR-SUPPORTED distributions, and links to their docs

CONTENT (Alphabetical):
* `Kubeflow on AWS`
* `Kubeflow on Azure`
* `Kubeflow on GCP`
* `Kubeflow on IBM Cloud`
* `Kubeflow on Openshift` (Combine: "Kubeflow Operator" and "Kubeflow on Openshift" page)
* `Kubeflow on MicroK8s` (Rename from "MicroK8s Kubeflow add-on" page)
* `Kubeflow with Charmed Operators` (Rename from "Kubeflow Charmed Operators" page)
* `Kubeflow with MiniKF`

### Community Supported
a TABLE which lists the currently maintained COMMUNITY-SUPPORTED distributions, and links to their docs

CONTENT (Alphabetical):
* `Kubeflow with ArgoCD` (New page)
* `Kubeflow with kfctl` (Rename from "kfctl" page)

## Next Steps
* links to important component docs "Pipelines", "Notebooks", etc.

[thesuperzapper]

@RFMVasconcelos there are quite a lot of renames here, but I think it will make the user experience easier.

I have used Kubeflow on XXX for cases were the "distribution" is a guide for using Kubeflow on a platform, and Kubeflow with XXX when the "distribution" is a tool for deploying/using kubeflow arbitrarily.

[rui-vas]

Thank you for getting this process started @thesuperzapper! This is going to make things much more clear to users 🚀

I like the majority of the proposal! Leaving a few comments:

## Overview

I guess we will keep the title and subtitle (or slightly tweak it) and so Overview would fall under this:

1. I would rather call it Introduction, simply because it lays the ground information required to understand the following steps, rather than summarizing what's coming » Just a detail :)
2. IMO, versioning should be part of the Kubeflow overview page. We can create a versioning section there and point to it from the Introduction section here with a quick summary.

## Path 1: Roll Your Own

I would go for a link instead of copying the instructions here for 2 reasons:

1. They are long and so would make other options hard to reach, people would have to scroll a lot if they do not want option 1.
2. It would be hard to guarantee that it is always up to date - contributors to manifests README would have to know that they needed to make PRs in both places at the same time. Or someone would have to verify this often.

### Vendor Supported

I would draw the distinction between platform-specific distributions and multi-platform distributions. I think this is what you have tried to achieve with the on XXX VS with XXX but IMO it is too subtle, might be confusing.

We could split into two tables:

Platform-specific distributions (Alphabetical):
* `Kubeflow on AWS`
* `Kubeflow on Azure`
* `Kubeflow on GCP`
* `Kubeflow on IBM Cloud`
* `Kubeflow on Openshift` 
* `Kubeflow on MicroK8s` 

Multi-platform distributions (Alphabetical):
* `Kubeflow with Charmed Operators` 
* `Kubeflow with MiniKF`

The rest LGTM!

[cvenets]

@RFMVasconcelos I agree with all your comments above.

I would rename Kubeflow with MiniKF to Kubeflow with Arrikto MiniKF to denote explicitly who is the vendor supporting the distro, so it is easy for new users. You may want to do the same for Charmed Operators (e.g., Canonical Charmed Operators). For the Platform-specific distros it is evident, so no need to do anything there.

Also, it may make sense for all the tables to go to the distributions page and leave here only a link to the distributions page, same as we do for Path 1, so the user doesn't have to scroll a lot, but I'll let you decide on this.

Thanks!

[rui-vas]

Looking at my previous proposal + @cvenets comments one option would be:

Platform-specific distributions (Alphabetical):
* `Kubeflow on AWS`
* `Kubeflow on Azure`
* `Kubeflow on GCP`
* `Kubeflow on IBM Cloud`
* `Kubeflow on Openshift` 

Multi-platform distributions (Alphabetical):
* `Arrikto MiniKF`
* `MicroK8s Kubeflow add-on`
* `Kubeflow Charmed Operators`

@cvenets maybe Arrikto MiniKF is shorter and better than Kubeflow with Arrikto MiniKF, WDYT?

// note 1: I moved MicroK8s from platform-specific to multi-platform, because being a small K8s, it can be run on multiple platforms.
// note 2: I think that with the separation of platform-specific and multi-platform distributions we don't need Kubeflow with to create this separation.

// Issue 1: I would like to have a way to show users on e.g. AWS that they can also use one of the multi-platform distributions on AWS, not necessarily the AWS-specific distribution. Any ideas?

@thesuperzapper WDYT?

[cvenets]

@RFMVasconcelos I agree with all your comments and notes.

Wrt to the issue, I agree as well. The only two ways I can think of are:

1. Add a parenthesis next to the multi-platform items, which will include all the currently supported platforms, e.g.,:

• Arrikto MiniKF (AWS, GCP, laptop/desktop)
• `MicroK8s Kubeflow add-on (..., ..., ...)
  ...

2. Change "Multi-platform distributions" to "Platform-agnostic distributions across clouds"

I'm not sure I can think of something to add on the first section, but maybe someone has an idea for this as well.

[cvenets]

@RFMVasconcelos note that we need to remove the kfctl entry from this page:

• Kubeflow with kfctl (Rename from "kfctl" page)

Take a look at #2604, which @castrojo just provided after today's update on kubeflow/manifests#1798 from vendors, where both Cisco and Arrikto dropped support for kfctl, and thus all corresponding docs become obsolete and out-of-date for 1.3.

[thesuperzapper]

@RFMVasconcelos

• I agree with splitting on single/multi platform
• I think MiniKF is a Platform-specific one, as its a single VM image on vagrant
• Re letting AWS/GCP users know there are other options, we will just say under "Multi-platform distributions" that these distributions support any existing + compliant K8S cluster

I think we should call the two paths:

• Path 1: Roll Your Own
  • "A warning that this is an advanced option, which is not officially supported by the project"
  • "A quick description of what this means, with a link to the kubeflow/manifests readme"
• Path 2: Use a Distribution
  • Platform-specific distributions
    • "A description that these could be anything from a managed service to a fully contained VM image"
  • Multi-platform distributions
    • "A description that these should support any existing & complaint K8S cluster"

---

I was thinking something like this for the distribution tables.

Platform-specific distributions:

Name	Maintained By
Kubeflow on AWS	AWS
Kubeflow on Azure	Azure
Kubeflow on GCP	GCP
Kubeflow on IBM Cloud	IBM Cloud
Kubeflow on Openshift	Red Hat
Kubeflow on MicroK8S	Canonical
Kubeflow on MiniKF	Arrikto

Multi-platform distributions:

Name	Maintained By
ArgoFlow	ArgoFlow Team
Charmed Operators	Canonical
Kfctl Command Line	N/A

NOTE:

• "Name" would be link to the distribution's docs
• "Maintained By" would link to the company/community support page
• We could add a single line "Description" to each distribution, but that seems like an opportunity for many issues, and could look like us favouring one over the other.

---

I am happy to have a crack at a PR it unless you really want to.

[cvenets]

@thesuperzapper please note the following:

I think MiniKF is a Platform-specific one, as its a single VM image on vagrant

This isn't really the case, since MiniKF is already available as a VM image on AWS Marketplace, GCP Marketplace, Vagrant Cloud, and will be coming on Microsoft platforms as well. The fact that it is packaged in an image doesn't really change its multi-platform nature.

"A warning that this is an advanced option, which is not officially supported by the project"

This doesn't hold. The Manifests WG maintain and guarantee that these instructions should work, so it is definitely supported.

[thesuperzapper]

@cvenets

Re MiniKF: I think its probably better to remove the distinction, and add a column to clarify, for example:

Name	Maintained By	Deployment Target
Kubeflow on AWS	AWS	EKS Clusters
Kubeflow on Azure	Azure	AKS Clusters
Kubeflow on GCP	GCP	GKE Clusters
Kubeflow on IBM Cloud	IBM Cloud	IKS Clusters
Kubeflow on Openshift	Red Hat	Openshift Clusters
Kubeflow on MicroK8S	Canonical	MicroK8S Clusters
MiniKF	Arrikto	AWS Marketplace, GCP Marketplace, Local VirtualBox
ArgoFlow	ArgoFlow Community	K8S Clusters with Argo-CD Installed
Charmed Operators	Canonical	K8S Clusters with Juju Installed

---

Re the warning: What I am trying to say is that users should not expect any environment-specific support from the Kubeflow Community for the "roll your own" path

[thesuperzapper]

@RFMVasconcelos and @cvenets I have raised a WIP PR for this refactor #2611

I will finish up the text-copy some time other than midnight my time!

[rui-vas]

Thank you @cvenets and @thesuperzapper for the comments on this front and for creating the WIP PR!

A few comments on your proposing table @thesuperzapper:

1. No separation, only 1 table: I think that deployment target or target platforms make things clear for users.
2. A proper map: I think we should not forget that this page is a gateway and that it should be clear to users where to click on that table. I think we should strict links to the Name column and rename that to Documentation - links in every column as in your PR will be hard to follow and drive users off the website.

I have MicroK8s and Charmed Operators specific suggestions, but I will add these to your PR. :)

(PS: @cvenets I deleted one comment from you because it was repeated)

[cvenets]

I agree, a single table is fine with the addition of the last column.

I agree with @RFMVasconcelos on 2. We don't want people to go off the website or confuse them. A single link to the corresponding docs should suffice.

I will comment on the PR as well.

Re the warning: What I am trying to say is that users should not expect any environment-specific support from the Kubeflow Community for the "roll your own" path

@thesuperzapper OK, this makes sense then, but I think this is pretty clear by the "on your own" part of the title of the section.

[davidspek]

@thesuperzapper For ArgoFlow I think the target should be Any K8S Clusters (or something similar), as the Argo CD installation is part of the deployment, and Argo CD does not technically need to run on the same cluster as Kubeflow. Otherwise user might think they need to figure out how to deploy Argo CD on their own before going through the documentation.

[rui-vas]

@thesuperzapper (and @davidspek) I love the energy behind ArgoFlow, but I feel a bit wary of adding it directly here as per your proposal.

According to #2611, the way you propose this table is to link the ArgoFlow documentation to its own repo. I am not sure what is the right way to proceed here. If creating appropriate docs in Kubeflow for this distribution and point from here.

I would overall want to make sure that the goal of this page as a gateway and map to Kubeflow docs is met.

I would suggest tackling this specific issue on a separate thread, making structure independent from content. WDYT?

[cvenets]

I would overall want to make sure that the goal of this page as a gateway and map to Kubeflow docs is met.

I agree with @RFMVasconcelos. All links in this page should redirect to Kubeflow docs, not external sites.

[thesuperzapper]

@RFMVasconcelos @cvenets regarding comment that we should only link to kubeflow.org docs

I actually think we should do the opposite (over time), just as kubernetes.io doesn't host EKS docs, we shouldn't host vendor specific docs, but rather link to parter websites.

This will do a few things:

1. Make it easier for distributions to update their docs
2. Prevents it looking like the community endorses any specific distribution
3. Encourage vendors to keep their docs updated (as it's gonna look bad for vendors if they neglect docs on their own website)

NOTE: This is not about the structure of the table, I agree with comments about improving how the links are displayed, and will update the PR

[Bobgy]

/reopen
After the PR is merged, some things should be fixed right now:

• [blocker] I think we are missing a redirect rule from the old page to the new page
• [blocker] https://deploy-preview-2611--competent-brattain-de2d6d.netlify.app/docs/started/getting-started/ is broken, we should update the "getting started" button url

ref: #2611 (comment)

[google-oss-robot]

@Bobgy: Reopened this issue.

In response to this:

/reopen
After the PR is merged, some things should be fixed right now:

• [blocker] I think we are missing a redirect rule from the old page to the new page
• [blocker] https://deploy-preview-2611--competent-brattain-de2d6d.netlify.app/docs/started/getting-started/ is broken, we should update the "getting started" button url

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.

[Bobgy]

and some ideas for further improvement:

• the link to manifest README should better pin to 1.3.0 release once we pin the final release
• I think we should add a column "Issue Tracker" where people can report distribution specific issues.

[Bobgy]

the immediate problems are fixed by #2635

Where do you plan to create a new issue tracking future improvements? Or shall we keep the discussion here?

[thesuperzapper]

@Bobgy lets make specific issues for any changes we want to make/discuss and close this out.