improve the "installing kubeflow" page

[thesuperzapper]

This PR improves the Getting Started / Installing Kubeflow page in the following ways:

• Splits the distributions tables into two sections:
  • "Active Distributions" - any distribution which has had an update within the last 6 months
  • "Legacy Distributions" - any not active distribution, currently only has:
    • Argoflow (Kubeflow 1.4)
    • Kubeflow on Azure (Kubeflow 1.2)
• Improves the readability of the distribution tables:
  • Removed the "version" column as it was quite messy, and often had incorrect information as distributions forgot to update it (replaced with "latest release" column)
  • Combines the distribution "links" into a single column (preparation for once TRACKING - remove distribution owned docs from website #3074 is resolved)
• Added a link to the "official website" of each distribution
• Changes the names of the following distributions to be more correct:
  • Kubeflow on OpenShift --> Open Data Hub
  • Kubeflow on Oracle Container Engine for Kubernetes --> Kubeflow on Oracle Cloud Infrastructure
• Improves the section header names:
  • Install a packaged Kubeflow distribution --> Packaged Distributions of Kubeflow
  • Install the Kubeflow Manifests manually --> Raw Kubeflow Manifests
• Improves the wording of warnings and other text.

Screenshot of the updated page:

[thesuperzapper]

@jbottum @annajung @DomFleischmann @zijianjoy I think this improvement will help users get started with kubeflow more easily, so would appreciate a review as soon as possible!

/assign @jbottum @annajung @DomFleischmann @zijianjoy

[jbottum]

@thesuperzapper thank you for these proposed updates. I see follow-up in two parts - one for the distribution listing and one on the Raw naming convention. I propose that Brad Cardwell (distribution liaison for KF v1.7) might want to help organize the distribution approvals from the distributions. Initially the Oracle and Openshift contacts should weight in, but I think this impacts all of the distributions. It is a good topic / proposal for the Kubeflow Summit session today and we will give it some exposure. As for the raw naming, I initially ok with it but would like to hear what other comments might be.

[jbottum]

@VaishnaviHire Is there someone from the OpenShift team that would like to comment on this proposal ?

[annajung]

Thanks for working on this! I think it makes sense to move the distributions that are no longer supported into the "legacy" section.

Left a few comments on a few concerns with what defines as "active" vs "legacy" and version removal

[google-oss-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: thesuperzapper
Once this PR has been reviewed and has the lgtm label, please ask for approval from zijianjoy by writing /assign @zijianjoy in a comment. For more information see the Kubernetes Code Review Process.

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

Needs approval from an approver in each of these files:

• content/en/docs/started/OWNERS

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

[thesuperzapper]

Quick update, I have improved the bullet point symbols after the discussion in #3381 (comment), see the screenshot at the top of the page.

[andreeamun]

Hello:) It is great you addressed this. One thing that has been raised in the past is the order that distributions are listed (based on this proposal in the Active distributions one). Is there any reason behind this?

Might be more efficient to list them alphabetically.

[thesuperzapper]

Hello:) It is great you addressed this. One thing that has been raised in the past is the order that distributions are listed (based on this proposal in the Active distributions one). Is there any reason behind this?

Might be more efficient to list them alphabetically.

@andreeamun I have left the order as it was for this PR, I think we can discuss the best (and more fair) ordering in a separate discussion.

I also think we need to confirm the "names" of distributions. The current names stem from a time when the community owned all the distributions. Now that the distributions are maintained externally, having them all called Kubeflow on XXXX is problematic (and hurts distributions not named like this) because it implies that it is the "official" way to deploy Kubeflow on XXXX.

Perhaps we should encourage distributions to name themselves something completely different, or suggest Kubeflow by YYYYY, where YYYYY is the maintainer of the distribution (for example, Kubeflow by Google Cloud or Kubeflow by AWS).

EDIT: the other name we can suggest is YYYYY Distribution of Kubeflow (which seems to be what google is using on their GitHub repo)

[thesuperzapper]

@zijianjoy and @annajung what do you think we need to get this merged?

I think the overall changes make the "installing kubeflow" page much easier to understand.

[annajung]

@thesuperzapper I am still concerned about the removal of the versions. Without the versions listed, tracking which Kubeflow versions each distribution support would be harder. In the future, how would we be able to determine which distributions are active vs. inactive without adding the manual work to check their external doc? Wouldn't it be better to keep this page as the source of truth and work with distributions to update it?

In addition, there is an open question about if all distributions listed in the "active" section support 1.6 that needs to be resolved before we can merge this PR.

If the initial goal is to separate active and inactive, I think you can still move forward by keeping the versions as is and just separating the distributions that support 1.3 and below (more than 12months+). wdyt?

[jbottum]

Some comments, 1) I expect we will have additional distributions: VMware, HP, Civo, DKube/OneConvergence, 2) as the list gets longer, it will be harder to keep updated, especially if we are displaying version numbers. 3) I like version numbers, but in reality, distributions will modify (so does the version number mean as much i.e. Arrikto distribution has things that might eclipse 1.6, even if the are publicly stating on 1.x).

[thesuperzapper]

@annajung @jbottum I have updated the PR with what I think is a good compromise.

1. I have updated the definition of "active" to be "having a release within the last 6 months"
2. I have added a "latest release" column to the table, which lists the date (with a citation) of the most recent release

In the future when we have "conformance testing" (kubeflow/kubeflow#6485), we can list which version of the Kubeflow "API" they are conformant with, which is more useful than listing "Kubeflow 1.X" as that is meaningless when we allow vendors to change anything they like about Kubeflow.

[jbottum]

@thesuperzapper @annajung Side note - perhaps instead of list distributions in alphabetical order, we list in order of date of 1st supported. This rewards the distributions that have been in the Community the longest and put them at the top of the list. Of course this assumes they have kept up with the subsequent releases.

[thesuperzapper]

@thesuperzapper @annajung Side note - perhaps instead of list distributions in alphabetical order, we list in order of date of 1st supported. This rewards the distributions that have been in the Community the longest and put them at the top of the list. Of course this assumes they have kept up with the subsequent releases.

@jbottum I think let's leave the re-ordering discussion to a separate PR, so we can get this update merged soon. Note, I have left the order unchanged in this PR (other than moving some distributions to the new "legacy" table).

---

EDIT: While I think we should discuss re-ordering in another PR, here are some more ideas for other metrics that we could order the table by:

• Number of active users (probably the best, but VERY hard to quantify)
• Number of unique contributors (based on public commits)
• Number of Google "results" from the name of the distribution in quotes (seems like a reasonable compromise which is non-trivial to manipulate)
  • NOTE: for distributions with names like "Kubeflow on XXXX" we might want to Use a search string like "Kubeflow on XXXXX" "Distribution"
• Number of stars on GitHub (issue is that not all distributions have a GitHub)

[thesuperzapper]

I just did a quick formatting improvement in b1287ad:

1. Used fewer words (to reduce the risk of text wrapping on smaller screens)
   • "Official Website" -> "Website"
   • "References" -> "Links"
2. Added line breaks after the date for the references in "Latest Release" (reduces column width)
3. Removed some unnecessary capital letters

Current Screenshot

Click to expand

[annajung]

If the kubeflow versions are replaced with the distributions' latest release date, can we make sure that all distributions list the dates?

tagging distribution owners for unknown values

[annajung]

@kimwnasptd is there something we can reference here to add the date of your latest release?

[thesuperzapper]

@kimwnasptd just to clarify, we need a publicly listed blog/changelog/release-page that confirms the release date.

For example, I have used https://docs.arrikto.com/Changelog.html for the "Arrikto Enterprise Kubeflow" distribution, but "Arrikto Kubeflow as a Service" dose not seem to have an equivalent page.

[annajung]

@julioo is there something we can refer here to add the date of your latest release?

[thesuperzapper]

@julioo just to clarify, we need a publicly listed blog/changelog/release-page that confirms the release date so we can link it.

[julioo]

@annajung @thesuperzapper, you're referring to the Oracle Kubernetes Engine release date?
https://docs.oracle.com/en-us/iaas/releasenotes/services/conteng/
for example
https://docs.oracle.com/en-us/iaas/releasenotes/changes/2aca54a0-5594-48f3-8c51-c126d22d4eda/

[thesuperzapper]

I wanted to share another proposal for how to order the "installing kubeflow" table.
(NOTE: I still think we should leave the order as is in this PR and do any re-order in a separate one)

I think we should sort the table alphabetically, but have separate tables for each "tier of partner" (think "platinum", "gold", and "silver"). Partners would attain tiers by accumulating points through their contributions and involvement in the project.

For example, some things which could give you points might be:

• length of involvement in the project
• number of FTE committed to the project (and how active they are)
• other contributions (like providing food at events, sponsoring testing infrastructure, etc)
• how consistently you upstream proprietary features back to the community
• the openness of your distribution (for example, less points for closed-off distributions, and more for fully open-source)

We will probably need to treat "non-commercial" (free, open source) partners with a different set of standards so that we don't end up with commercial distributions crowding them out.

---

Separately, we will need to rename distributions which are called things like Kubeflow on XXXXX as this is very misleading for new users who will believe that this is the only way to deploy on XXXXX (as XXXXX is often a platform, like AWS).

In most cases, a rename to something like XXXXX Distribution of Kubeflow will be acceptable (like Google Cloud Distribution of Kubeflow already has), but I would also love to see some more exotic names which don't have the word Kubeflow in it (like Open Data Hub)!

[jbottum]

@johnugeorge Hey Johnu, this update show that Nutanix does not have a current distribution of Kubeflow. Would you please review and provide the correct info ?

[jbottum]

@thesuperzapper Hi Mathew - I believe your proposal on ordering and levels (especially using sweat equity) has merit. Per your/my earlier comments, I think that the re-ordering (and the distribution requirement restructuring) need to be in separate PRs. In the short term (by the end of the month or sooner), I propose that we need to add Oracle, Telekom, and Vmware and make sure the info listed for each distribution is correct. Question - Should we require a looks good to me from each of the distribution contacts before this is merged ?

[johnugeorge]

@thesuperzapper Nutanix supports Kubeflow 1.6 and was announced already kubeflow/manifests#2221 (comment). Please move it to active distributions.

Ref: nutanix/karbon-platform-services#94

On a larger note, what are we aiming to achieve with this change? This change needs more discussion before merge.

[thesuperzapper]

@thesuperzapper Nutanix supports Kubeflow 1.6 and was announced already kubeflow/manifests#2221 (comment). Please move it to active distributions.

Ref: nutanix/karbon-platform-services#94

@johnugeorge I have updated the table to reflect this information in 98d74ba

PS: I think it's a little strange to use a GitHub comment to announce a release, that's obviously up to Nutanix to decide how they do things.

On a larger note, what are we aiming to achieve with this change? This change needs more discussion before merge.

This update is about a number of things (see the PR description), but primarily it's about making the tables more readable, and preparing for when this page will be the only reference to distributions on the kubeflow.org site (e.g. we will be linking to each distributions site, but not hosting their docs for them, see #3074).

[thesuperzapper]

@zijianjoy all Netelify builds are now failing because (we need to update the build image in the Netelify admin page), do you have access to update it?

I have raised an issue to discuss this problem: #3404

[gkcalat]

@thesuperzapper, please push a new commit to trigger the tests

[thesuperzapper]

@gkcalat thanks for that!

---

@annajung @liuqi I have rebased for #3396, however, I can't find a public announcement/changelog for Kubeflow on vSphere, so I have put "unknown" as the "latest release date" for now.

Do you have a public place where you announced the release of Kubeflow on vSphere for Kubeflow 1.6?

For example, others are using the "releases" page on GitHub, or their official blog posts (a big goal of this PR is to have each distribution provide a "latest release date" with a link as evidence for this date).

---

For @zijianjoy and everyone watching, here is a screenshot from this PR (as it currently stands).

[thesuperzapper]

Hey all, I have created a new PR that makes the style changes, without removing the version // adding the release dates.

Please help review #3440