add "distribution name" notice on "installing kubeflow" + style improvements #3643

thesuperzapper · 2023-12-05T21:50:42Z

The changes in this PR:

The main purpose of this PR is to add a warning that says Kubeflow on <PLATFORM> is just name, and not the only way to install Kubeflow on that platform.
We also update the "header colors" of the tables, to look nicer.
We also update the text above each table to be more correct.
We also updated the text for the "raw manifests", to better explain that using them requires "manual patches of YAML".

After we merge this, we need to move the Kubeflow on AWS distribution to the legacy distribution table, there is an existing PR to do this:

move Kubeflow on AWS to legacy distributions #3641

Screenshot

google-oss-prow · 2023-12-05T22:12:42Z

[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 assign animeshsingh for approval. 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:

OWNERS

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

thesuperzapper · 2023-12-05T22:16:50Z

@zijianjoy can review this and approve if you think it's an improvement.

I think it's an important change, because right now, users are confused about the Kubeflow on XXXX distributions, and this PR adds a notice that tells users that these are not "official" from Kubeflow's perspective, they are just their names.

jbottum · 2024-01-30T00:53:11Z

I am supportive of the additional language on distribution names. On the other changes, I am questioning if the community has agreed on the 6 month rule to define legacy distributions. This seems like a policy that needs to be agreed upon before making web site updates.

thesuperzapper · 2024-02-06T18:20:16Z

@jbottum the main feedback from the community call was about the wording of the "distribution name notice", based on that, I have updated it to say "not the only", rather than "not the official":

Also, regarding the 6-month rule, let's discuss that in a separate change, because that wording is currently on the website, and the other changes from this PR are very helpful to new users.

If we are happy with the change I would love to get this merged, so people know that "Kubeflow on AWS" is not the only way to use Kubeflow on AWS (especially now that "Kubeflow on AWS" is no longer maintained).

jbottum · 2024-02-20T17:10:57Z

I am ok with these changes

andreyvelich

/assign @kubeflow/kubeflow-steering-committee @kubeflow/wg-manifests-leads @kubeflow/wg-training-leads @kubeflow/wg-notebooks-leads for review

andreyvelich · 2024-02-20T17:43:58Z

content/en/docs/started/installing-kubeflow.md

-<b>advanced users may choose to install the manifests directly</b> by following <a href="https://github.com/kubeflow/manifests#installation">these instructions</a>.
+The raw <a href="https://github.com/kubeflow/manifests"><code>kubeflow/manifests</code></a> are aggregated by the <a href="https://github.com/kubeflow/community/tree/master/wg-manifests">Manifests Working Group</a> 
+and are intended to be used as the <strong>base of packaged distributions</strong>.
+However, advanced users that are willing to make manual patches may choose to install the manifests directly by following <a href="https://github.com/kubeflow/manifests#installation">these instructions</a>.


What do you mean by manual patches here ?

I mean in terms of changing the YAML manifests themselves (customize overlays, ConfigMaps, etc), for anything more than a fully default install.

This is the key point people need to know, that if they use the manifests, they need to be comfortable with making Kubernetes patches.

Basically, they need to modify Kustomize overlays manually if they want to have any changes to the default Kubeflow installation. Maybe we should say this rather than manual patches. I am not sure if users will easily understand this message.

I am not sure it's super helpful to list out the possible kinds of manual patches, as there are so many.

Do you have a specific wording you think would help people, without confusing them?

Maybe we could say:

However, advanced users may choose to install the manifests directly by following these instructions. Users can modify the Kubeflow components kustomize manifests to apply required changes before deploying Kubeflow.

I have pushed some updates, which remove the "manual patches" stuff.

It also links users to the actual release branches of the manifests, rather than master, which may or may not actually work.

thesuperzapper · 2024-02-20T20:15:56Z

@andreyvelich based on your comments in the meeting today, I pushed a small update to the PR with the following changes:

Added "What is Kubeflow?" to before the Kubeflow introduction at the top
- Linked the "Introduction" and "Architecture" pages more clearly at the top.
Updated the information in the "Raw Kubeflow Manifests":
- Now links directly to the specific v1.8.0 release tags in kubeflow/manifests rather than linking people to master (which may not be installable at any specific time).

andreyvelich · 2024-02-20T23:08:33Z

content/en/docs/started/installing-kubeflow.md

+1. [__Packaged Distributions__](#packaged-distributions-of-kubeflow) <sup>(recommended)</sup>
+2. [__Raw Manifests__](#raw-kubeflow-manifests) <sup>(advanced users)</sup>


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.

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.

We really want to present Kubeflow as a unified platform, rather than a collection of tools.

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

@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.

andreyvelich · 2024-02-22T14:14:10Z

content/en/docs/started/installing-kubeflow.md

-1. [Use a packaged distribution](#packaged-distributions-of-kubeflow)
-2. [Use the raw manifests](#raw-kubeflow-manifests) <sup>(for advanced users)</sup>
+1. [__Packaged Distributions__](#packaged-distributions-of-kubeflow)
+2. [__Raw Manifests__](#raw-kubeflow-manifests) <sup>(advanced users)</sup>


Do you need to remove for advance users as well ?
Since we removed warning from raw manifests installation section.

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.

From my point of view, we should even remove these warnings.
I think, users already understood this by reading the following:
"""
Packaged distributions are maintained by various organizations and typically aim to provide a simplified installation and management experience for Kubeflow.
"""

Would do others think @kubeflow/wg-manifests-leads @kubeflow/kubeflow-steering-committee ?

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.

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.

Just so we are clear, the existing website says (for advanced users), and this PR just removes the word "for" so it becomes (advanced users), so its not really a significant change.

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.

That makes sense @thesuperzapper. Let's discuss these changes in separate PR, if @juliusvonkohout are ok with it.

Yes of course, if is really just removing "for"

andreyvelich · 2024-02-27T15:14:44Z

I think, we can merge this PR given our discussions in #3643 (comment) and #3643 (comment)
/lgtm
/assign @kubeflow/kubeflow-steering-committee @juliusvonkohout @james-jwu @zijianjoy

thesuperzapper · 2024-02-27T17:54:41Z

@zijianjoy @james-jwu because this updates the CSS stylesheet, we need a root approver.

This PR should be ready to merge now, if you approve.

NOTE: the DOC check is not actually marked as "required", so it can be merged if approved.

andreyvelich

/assign @james-jwu @jbottum @johnugeorge @terrytangyuan @zijianjoy @juliusvonkohout if you are ok with these changes let's merge this PR.

juliusvonkohout · 2024-03-01T10:11:19Z

content/en/docs/started/installing-kubeflow.md


-The Kubeflow community is not able to provide support for environment-specific issues when using the raw manifests.
+When using the raw manifests, the Kubeflow community is not able to provide support for environment-specific issues or custom configurations.


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.

@juliusvonkohout Can you submit followup PR to make this change ? I think, this PR is opened for so long and we should move forward.

andreyvelich · 2024-03-01T19:57:56Z

/hold due to #3693

thesuperzapper · 2024-06-19T17:50:29Z

Closing because we merged #3693

google-oss-prow bot requested review from alfsuse and knkski December 5, 2023 21:50

google-oss-prow bot added the size/S label Dec 5, 2023

add distribution name notice on "installing kubeflow"

218eff7

thesuperzapper force-pushed the add-notice-on-distros-page branch from b99f5d9 to 218eff7 Compare December 5, 2023 22:12

google-oss-prow bot added size/M and removed size/S labels Dec 5, 2023

thesuperzapper changed the title ~~add distribution name notice on "installing kubeflow"~~ add distribution name notice on "installing kubeflow" + style improvements Dec 5, 2023

thesuperzapper mentioned this pull request Dec 5, 2023

move Kubeflow on AWS to legacy distributions #3641

Closed

thesuperzapper changed the title ~~add distribution name notice on "installing kubeflow" + style improvements~~ add "distribution name" notice on "installing kubeflow" + style improvements Dec 7, 2023

thesuperzapper mentioned this pull request Jan 29, 2024

[Kubeflow 1.9] Distributions and Kubeflow 1.9 kubeflow/manifests#2611

Closed

update distribution name notice

2fbd31a

andreyvelich reviewed Feb 20, 2024

View reviewed changes

update "raw manifests" wording and add intro heading

4052ece

small typo

3fd0a3d

andreyvelich reviewed Feb 20, 2024

View reviewed changes

updates from suggestions

18d610f

andreyvelich reviewed Feb 22, 2024

View reviewed changes

google-oss-prow bot assigned andreyvelich Feb 27, 2024

google-oss-prow bot added the lgtm label Feb 27, 2024

andreyvelich reviewed Feb 29, 2024

View reviewed changes

juliusvonkohout reviewed Mar 1, 2024

View reviewed changes

andreyvelich mentioned this pull request Mar 1, 2024

Change Kubeflow Distributions Table #3693

Merged

google-oss-prow bot added the do-not-merge/hold label Mar 1, 2024

thesuperzapper closed this Jun 19, 2024

thesuperzapper deleted the add-notice-on-distros-page branch September 4, 2024 17:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add "distribution name" notice on "installing kubeflow" + style improvements #3643

add "distribution name" notice on "installing kubeflow" + style improvements #3643

thesuperzapper commented Dec 5, 2023 •

edited

Loading

google-oss-prow bot commented Dec 5, 2023

thesuperzapper commented Dec 5, 2023

jbottum commented Jan 30, 2024

thesuperzapper commented Feb 6, 2024

jbottum commented Feb 20, 2024

andreyvelich left a comment

andreyvelich Feb 20, 2024

thesuperzapper Feb 20, 2024

andreyvelich Feb 20, 2024

thesuperzapper Feb 20, 2024

andreyvelich Feb 20, 2024 •

edited

Loading

thesuperzapper Feb 20, 2024

thesuperzapper commented Feb 20, 2024

andreyvelich Feb 20, 2024 •

edited

Loading

thesuperzapper Feb 20, 2024

andreyvelich Feb 21, 2024

thesuperzapper Feb 21, 2024

andreyvelich Feb 22, 2024

thesuperzapper Feb 22, 2024

andreyvelich Feb 23, 2024

thesuperzapper Feb 23, 2024 •

edited

Loading

juliusvonkohout Feb 26, 2024

thesuperzapper Feb 26, 2024

andreyvelich Feb 27, 2024

juliusvonkohout Feb 28, 2024

andreyvelich commented Feb 27, 2024

thesuperzapper commented Feb 27, 2024 •

edited

Loading

andreyvelich left a comment

juliusvonkohout Mar 1, 2024 •

edited

Loading

andreyvelich Mar 1, 2024 •

edited

Loading

andreyvelich commented Mar 1, 2024 •

edited

Loading

thesuperzapper commented Jun 19, 2024

		1. [__Packaged Distributions__](#packaged-distributions-of-kubeflow) <sup>(recommended)</sup>
		2. [__Raw Manifests__](#raw-kubeflow-manifests) <sup>(advanced users)</sup>


		The Kubeflow community is not able to provide support for environment-specific issues when using the raw manifests.
		When using the raw manifests, the Kubeflow community is not able to provide support for environment-specific issues or custom configurations.

add "distribution name" notice on "installing kubeflow" + style improvements #3643

add "distribution name" notice on "installing kubeflow" + style improvements #3643

Conversation

thesuperzapper commented Dec 5, 2023 • edited Loading

Screenshot

google-oss-prow bot commented Dec 5, 2023

thesuperzapper commented Dec 5, 2023

jbottum commented Jan 30, 2024

thesuperzapper commented Feb 6, 2024

jbottum commented Feb 20, 2024

andreyvelich left a 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

Choose a reason for hiding this comment

andreyvelich Feb 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thesuperzapper commented Feb 20, 2024

andreyvelich Feb 20, 2024 • edited Loading

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thesuperzapper Feb 23, 2024 • edited Loading

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

andreyvelich commented Feb 27, 2024

thesuperzapper commented Feb 27, 2024 • edited Loading

andreyvelich left a comment

Choose a reason for hiding this comment

juliusvonkohout Mar 1, 2024 • edited Loading

Choose a reason for hiding this comment

andreyvelich Mar 1, 2024 • edited Loading

Choose a reason for hiding this comment

andreyvelich commented Mar 1, 2024 • edited Loading

thesuperzapper commented Jun 19, 2024

thesuperzapper commented Dec 5, 2023 •

edited

Loading

andreyvelich Feb 20, 2024 •

edited

Loading

andreyvelich Feb 20, 2024 •

edited

Loading

thesuperzapper Feb 23, 2024 •

edited

Loading

thesuperzapper commented Feb 27, 2024 •

edited

Loading

juliusvonkohout Mar 1, 2024 •

edited

Loading

andreyvelich Mar 1, 2024 •

edited

Loading

andreyvelich commented Mar 1, 2024 •

edited

Loading