Closed thesuperzapper closed 3 years ago
@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.
Thank you for getting this process started @thesuperzapper! This is going to make things much more clear to users :rocket:
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:
Introduction
, simply because it lays the ground information required to understand the following steps, rather than summarizing what's coming » Just a detail :) 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:
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!
@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!
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?
@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:
Arrikto MiniKF
(AWS, GCP, laptop/desktop)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.
@RFMVasconcelos note that we need to remove the kfctl entry from this page:
Kubeflow with kfctl
(Rename from "kfctl" page)Take a look at https://github.com/kubeflow/website/pull/2604, which @castrojo just provided after today's update on https://github.com/kubeflow/manifests/issues/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.
@RFMVasconcelos
I think we should call the two paths:
kubeflow/manifests
readme"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:
I am happy to have a crack at a PR it unless you really want to.
@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.
@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
@RFMVasconcelos and @cvenets I have raised a WIP PR for this refactor https://github.com/kubeflow/website/pull/2611
I will finish up the text-copy some time other than midnight my time!
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:
deployment target
or target platforms
make things clear for users.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)
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.
@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.
@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?
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.
@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:
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
/reopen After the PR is merged, some things should be fixed right now:
ref: https://github.com/kubeflow/website/pull/2611#issuecomment-824668748
@Bobgy: Reopened this issue.
and some ideas for further improvement:
the immediate problems are fixed by https://github.com/kubeflow/website/pull/2635
Where do you plan to create a new issue tracking future improvements? Or shall we keep the discussion here?
@Bobgy lets make specific issues for any changes we want to make/discuss and close this out.
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:
kubeflow/manifests
yourself, with no supportI think this leaves us with the following sections in "Getting Started" / "Installing Kubeflow":