add "distribution name" notice on "installing kubeflow" + style improvements #3643
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,34 +5,48 @@ weight = 20 | |
|
|
||
| +++ | ||
|
|
||
| ### What is Kubeflow? | ||
|
|
||
| Kubeflow is an end-to-end Machine Learning (ML) platform for Kubernetes, it provides components for each stage in the ML lifecycle, from exploration through to training and deployment. | ||
| Operators can choose what is best for their users, there is no requirement to deploy every component. | ||
|
|
||
| Learn more about Kubeflow on the [Introduction](/docs/started/introduction/) and [Architecture](/docs/started/architecture/) pages. | ||
|
|
||
| ### How to install Kubeflow? | ||
|
|
||
| Anywhere you are running Kubernetes, you should be able to run Kubeflow. | ||
| There are two primary ways to install Kubeflow: | ||
|
|
||
| 1. [__Packaged Distributions__](#packaged-distributions-of-kubeflow) <sup>(recommended)</sup> | ||
| 2. [__Raw Manifests__](#raw-kubeflow-manifests) <sup>(advanced users)</sup> | ||
|
There was a problem hiding this comment. Do you need to remove for advance users as well ? There was a problem hiding this comment. We still kind of have a warning, it's just less forceful. But either way, installing from the manifests is really for advanced users only, we don't want people new to Kubeflow/Kubernetes thinking that its a good place to start. There was a problem hiding this comment. From my point of view, we should even remove these warnings. Would do others think @kubeflow/wg-manifests-leads @kubeflow/kubeflow-steering-committee ? There was a problem hiding this comment. I strongly think we need to keep a warning of some kind (for the raw manifests). The new warning from this PR is more specific that users need to understand Kubernetes, Istio and Kubeflow itself, but is overall less forceful (because if someone really is experienced, they shouldn't be afraid of it, but they should know what they're getting themselves into). Kubeflow and it's dependencies are really one of the most complicated things people regularly deploy on Kubernetes. There was a problem hiding this comment. I agree with Andrew here. Let's rather work with the smallest denominator and refine later on if needed. Then we can merge this PR without the warning and bring any controversial ideas to the KSC agenda. There was a problem hiding this comment. Just so we are clear, the existing website says I can re-add the "for" if you like, lol. If we want to change how we present the "raw manifests" to be a non-advanced option, we should do that in a separate PR, after a lot of community discussion. There was a problem hiding this comment. That makes sense @thesuperzapper. Let's discuss these changes in separate PR, if @juliusvonkohout are ok with it. There was a problem hiding this comment. Yes of course, if is really just removing "for" |
||
|
|
||
| <a id="packaged-distributions"></a> | ||
| <a id="install-a-packaged-kubeflow-distribution"></a> | ||
| ## Packaged Distributions of Kubeflow | ||
|
|
||
| Packaged distributions are maintained by various organizations and typically aim to provide a simplified installation and management experience for Kubeflow. | ||
|
|
||
| {{% alert title="Conformance and Certification" color="warning" %}} | ||
| Packaged distributions are developed and supported by their respective maintainers. | ||
| The Kubeflow community <strong>does not endorse or certify</strong> any specific distribution. | ||
|
|
||
| In the near future, there are plans to introduce <a href="https://github.com/kubeflow/community/blob/master/proposals/kubeflow-conformance-program-proposal.md">conformance testing for distributions</a>, you may track progress on this initiative by following <a href="https://github.com/kubeflow/kubeflow/issues/6485">kubeflow/kubeflow#6485</a>. | ||
| {{% /alert %}} | ||
|
|
||
| {{% alert title="Distribution Names" color="info" %}} | ||
| Some packaged distributions have names like `Kubeflow on <PLATFORM>`. | ||
| Please note, they are __not__ the only way to use Kubeflow on that platform, it is simply the name of a distribution. | ||
|
|
||
| There are discussions about renaming these distributions to avoid confusion with others that may be available on the same platform. | ||
| {{% /alert %}} | ||
|
|
||
| ### Active Distributions | ||
|
|
||
| The following table lists <strong>active distributions</strong> which are <em>currently maintained</em> by their respective maintainers. | ||
|
|
||
| <div class="table-responsive distributions-table-active"> | ||
| <table class="table table-bordered"> | ||
| <thead> | ||
| <tr> | ||
| <th>Name</th> | ||
| <th>Maintainer</th> | ||
|
|
@@ -68,7 +82,6 @@ The following table lists <b>active distributions</b> that have <b>had a recent | |
| 1.7.0 <sup>[<a href="https://github.com/Azure/kubeflow-aks/releases/tag/v1.7.0">Release Notes</a>]</sup> | ||
| </td> | ||
| </tr> | ||
| <tr> | ||
| <td>Kubeflow on Google Cloud</td> | ||
| <td>Google Cloud</td> | ||
|
|
@@ -164,11 +177,11 @@ The following table lists <b>active distributions</b> that have <b>had a recent | |
|
|
||
| ### Legacy Distributions | ||
|
|
||
| The following table lists <strong>legacy distributions</strong> which have <em>not had a recent release</em> (within the last 6 months), or whose maintainers have indicated that they are <em>no longer actively maintaining the distribution</em>. | ||
|
|
||
| <div class="table-responsive distributions-table-legacy"> | ||
| <table class="table table-bordered"> | ||
| <thead> | ||
| <tr> | ||
| <th>Name</th> | ||
| <th>Maintainer</th> | ||
|
|
@@ -229,17 +242,25 @@ The following table lists <b>legacy distributions</b> which have <b>not had a re | |
| <a id="install-the-kubeflow-manifests-manually"></a> | ||
| ## Raw Kubeflow Manifests | ||
|
|
||
| The raw Kubeflow Manifests are aggregated by the [Manifests Working Group](https://github.com/kubeflow/community/tree/master/wg-manifests) | ||
| and are intended to be used as the __base of packaged distributions__. | ||
|
|
||
| Very advanced users may choose to install the manifests for a specific Kubeflow version by following the instructions in the `README` of the [`kubeflow/manifests`](https://github.com/kubeflow/manifests) repository. | ||
|
|
||
| - [__Kubeflow 1.8:__](/docs/releases/kubeflow-1.8/) | ||
| - [`v1.8-branch`](https://github.com/kubeflow/manifests/tree/v1.8-branch#installation) <sup>(development branch)</sup> | ||
| - [`v1.8.0`](https://github.com/kubeflow/manifests/tree/v1.8.0#installation) | ||
| - [__Kubeflow 1.7:__](/docs/releases/kubeflow-1.7/) | ||
| - [`v1.7-branch`](https://github.com/kubeflow/manifests/tree/v1.7-branch#installation) <sup>(development branch)</sup> | ||
| - [`v1.7.0`](https://github.com/kubeflow/manifests/tree/v1.7.0#installation) | ||
|
|
||
| {{% alert title="Warning" color="warning" %}} | ||
| Kubeflow is a complex system with many components and dependencies, using the raw manifests requires a deep understanding of Kubernetes, Istio, and Kubeflow itself. | ||
|
|
||
| When using the raw manifests, the Kubeflow community is not able to provide support for environment-specific issues or custom configurations. | ||
|
There was a problem hiding this comment. What about "When using the raw manifests, the Kubeflow maintainers will not provide unpaid support for environment-specific issues or custom configurations. Nevertheless we welcome contributions and bug reports very much. If you need individual support, please consider using a packaged distribution or paid consulting." instead of "When using the raw manifests, the Kubeflow community is not able to provide support for environment-specific issues or custom configurations. If you need support, please consider using a packaged distribution." Disclaimer: I do Kubeflow Consulting, probably @thesuperzapper as well. But i think it is fair to mention that in general next to packaged commercial distributions. There was a problem hiding this comment. @juliusvonkohout Can you submit followup PR to make this change ? I think, this PR is opened for so long and we should move forward. |
||
| If you need support, please consider using a [packaged distribution](#packaged-distributions-of-kubeflow). | ||
| {{% /alert %}} | ||
|
|
||
| <a id="next-steps"></a> | ||
| ## Next steps | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
TBH, I would avoid to say that Package distribution is recommended way of installing Kubeflow. I think, users should chose what they want without explicit notice.
Also, in the following PRs I would like to have 3rd option: Kubeflow Component Standalone, which will explain that Kubeflow is composable and will link to independent components installation guides.
That will help users to understand that they can use individual Kubeflow component separately.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree we should not technically "recommend" anything, I have updated the PR.
Regarding adding a third "option" of installing standalone components, I am not sure that it's quite the right way to present it. We really want to present Kubeflow as a unified platform, rather than a collection of tools.
I am not sure if it's a good idea to link people to guides that show how to install specific components, not as part of the larger platform.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think, this is debatable. One of the big advantages of Kubeflow is that it could be easily integrated into existing ML platforms without any changes.
For example, if users just need engine for Training, they can use Training Operator or engine for Serving they can use KServe.
I know many large enterprises who are using individual Kubeflow components since they already have some ML capabilities in their platforms.
If we explain Kubeflow microservice architecture and composability properly we will get more attraction from the ML community and other companies.
cc @bigsur0
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@andreyvelich either way, we can discuss that in a future PR. I think this PR is probably ready to merge now, unless you have any other concerns?
It's critical we get this merged, to help users understand that "Kubeflow on XXXX" does not mean that it's the only way to install Kubeflow on that platform.