Katib v1beta1 documentation update by andreyvelich · Pull Request #2312 · kubeflow/website

andreyvelich · 2020-10-26T17:31:51Z

Related: kubeflow/katib#1360.
Blocked by: kubeflow/community-distribution#1593.
I updated docs for Katib v1beta1. I made few changes:

Update reference docs for v1beta1. @8bitmp3 @RFMVasconcelos Do we want to have v1alpha3 reference since all docs are written for v1beta1 ?
Fix few broken links.
Rename hyperparameter-tuning section to katib to make it clearer, since we are building AutoML project. What do you think about it @8bitmp3 @RFMVasconcelos ?
Add missing links for the examples, controller components, etc.
Update images.

I am still waiting for the pending PRs (I need to update docker images and few UI images., but it would be great if you can start to review it!

/assign @gaocegege @johnugeorge
/cc @8bitmp3 @RFMVasconcelos

kubeflow-bot · 2020-10-26T17:32:01Z

This change is

rui-vas · 2020-10-28T14:10:35Z

Hi @andreyvelich !

Thank you for this update! Replying by point:

Update reference docs for v1beta1. @8bitmp3 @RFMVasconcelos Do we want to have v1alpha3 reference since all docs are written for v1beta1 ?

You're asking if we want to keep a v1alpha3 version of the docs, now that we're updating Katib to v1beta1, correct?
If so:

When will these docs be effective? If we're launching v1beta1 with Kubeflow v1.2, would it make sense to include this in v1.2 of the docs?
If so, we can simply add a reference to v1alpha3 saying that docs can be found in Kubeflow v1.1 docs (with a link)

WDYT?

Rename hyperparameter-tuning section to katib to make it clearer, since we are building AutoML project. What do you think about it @8bitmp3 @RFMVasconcelos ?

LGTM.

rui-vas

One other point was the name change from Katib to something else. If we plan to do that, should we already make changes accordingly?

Any decision on that front?

andreyvelich · 2020-10-28T16:08:18Z

Thank you for the comment @RFMVasconcelos!

You're asking if we want to keep a v1alpha3 version of the docs, now that we're updating Katib to v1beta1, correct?
If so:

When will these docs be effective? If we're launching v1beta1 with Kubeflow v1.2, would it make sense to include this in v1.2 of the docs?

These docs will be effective after we merge: kubeflow/community-distribution#1593.
Including docs in V1.2 makes sense to me. I assume that website master branch will be point to 1.2 Kubeflow release, right ? If so, I am writing these docs to the appropriate branch.

If so, we can simply add a reference to v1alpha3 saying that docs can be found in Kubeflow v1.1 docs (with a link)

I think, it's a good idea. I will add v1alpha3 reference docs and add link to 1.1. Is there any way to get link for 1.1 docs? I found only 1.0 link: https://v1-0-branch.kubeflow.org/.

andreyvelich · 2020-10-28T16:10:43Z

One other point was the name change from Katib to something else. If we plan to do that, should we already make changes accordingly?

Any decision on that front?

I think we can stick with Katib name for Kubeflow 1.2.
If we decide to rename the project after 1.2, I will submit separate PR to make changes in the docs.

WDYT @gaocegege @johnugeorge ?

andreyvelich · 2020-10-28T21:07:52Z

Preview: https://deploy-preview-2312--competent-brattain-de2d6d.netlify.app/.

I have updated doc with v1alpha3 reference.

/cc @RFMVasconcelos @gaocegege @johnugeorge

rui-vas

Looking great!

You are indeed writing to the right branch! What we need to do is create the v1.1 branch and update master to be v1.2.

Let me create an issue about it :)

rui-vas · 2020-10-30T09:50:57Z

Oh, it looks like there is one already -> #2322

andreyvelich · 2020-10-30T14:46:27Z

Thanks @RFMVasconcelos.
Do you have any comments/objections on the doc changes in this PR?

andreyvelich · 2020-11-02T16:55:50Z

@RFMVasconcelos @8bitmp3 @gaocegege @johnugeorge I removed WIP status, since kubeflow/community-distribution#1593 is ready to merge. If you have any objections and comments on this PR, please let me know.
If not, we can merge it and start work on other Katib documentation PRs

8bitmp3

@andreyvelich Thanks for the PR!

I've added a few suggestions and comments. Feel free to disregard them 👍

Maybe in the Katib explanation in /components/katib/overview.md we could also add a small link for all the new ML users about AutoML (e.g. https://www.fast.ai/2018/07/16/auto-ml2/) and/or Microsoft Azure, Google Cloud and AWS AutoML solution docs?

Thank you for your help!

Update: also maybe we should move the "about" section up in overview.md such that:

Katib is a Kubernetes-native project for automated machine learning (AutoML) —
it's a system for hyperparameter tuning and neural architecture search. 
Katib supports a number of machine learning frameworks, including
TensorFlow, MXNet, PyTorch, XGBoost, and others.
The [Katib project](https://github.com/kubeflow/katib) is open source.
The [developer guide](https://github.com/kubeflow/katib/blob/master/docs/developer-guide.md)
is a good starting point for developers who want to contribute to the project.

8bitmp3 · 2020-11-02T21:01:38Z

+This page describes information about
+[Katib config](https://github.com/kubeflow/katib/blob/master/manifests/v1beta1/katib-controller/katib-config.yaml).
+
+Katib config is the Kubernetes
+[Config Map](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) that contains information about:


Thank you for the PR @andreyvelich

Hi, what do you think of this suggestion?

"refactor" to 'This page describes Katib config — the Kubernetes Config Map that contains information about:'

Suggested change

This page describes information about

[Katib config](https://github.com/kubeflow/katib/blob/master/manifests/v1beta1/katib-controller/katib-config.yaml).

Katib config is the Kubernetes

[Config Map](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) that contains information about:

This page describes

[Katib config](https://github.com/kubeflow/katib/blob/master/manifests/v1beta1/katib-controller/katib-config.yaml) —

the Kubernetes

[Config Map](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) that contains information about:

Agree, changed.

8bitmp3 · 2020-11-02T21:04:47Z

+
+You can edit this Config Map even after deploying Katib.
+
+If you deploy Katib in Kubeflow namespace, to edit Katib config run this:


Maybe just change the order here, use a different (present continuous) tense, and "the" (the definite article) (I checked with the K8s guide, as I'm not 100% sure about these):

Suggested change

If you deploy Katib in Kubeflow namespace, to edit Katib config run this:

If you are deploying Katib in the Kubeflow namespace, run this command to edit your Katib config:

Agree, changed.

8bitmp3 · 2020-11-02T21:10:47Z

+
+`kubectl edit configMap katib-config -n kubeflow`
+


Suggestion - use code style/code font/code block/codefence (K8s style guide, Google style guide:

Suggested change

`kubectl edit configMap katib-config -n kubeflow`

```shell

kubectl edit configMap katib-config -n kubeflow

```

(without the tabs that indent the code block - they render differently if I remove them)

@8bitmp3 Should we use ```shell everywhere?
e.g. https://github.com/kubeflow/website/blame/master/content/en/docs/components/hyperparameter-tuning/hyperparameter.md#L144 ?

@8bitmp3 I've just seen you comment: https://github.com/kubeflow/website/pull/2320/files#r516300401 about it.
Will do the change in this PR.

Done in fe91e74.

8bitmp3 · 2020-11-02T21:11:47Z

+
+All of these settings except **`image`** can be omitted. If you don't specify any other settings, default value is set.
+
+1. `image` - Docker image for the `File` metrics collector's container.


Suggested change

1. `image` - Docker image for the `File` metrics collector's container.

1. `image` - a Docker image for the `File` metrics collector's container.

Agree, changed.
@8bitmp3 I made all list items with not capital letter to be consistent (e.g. https://github.com/kubeflow/website/blame/62aba5ce7a065eb2b60d6b7884f4ab075be33fcc/content/en/docs/components/katib/katib-config.md#L66)
WDYT ?

8bitmp3 · 2020-11-02T21:42:46Z

+Katib is Kubernetes-native project for automated machine learning (AutoML).
+Use Katib for automated tuning of your machine learning (ML) model's hyperparameters and architecture.


Suggestions:

I think lines 87-95 about "the Katib project" should be right in the beginning of overview.md:

Suggested change

Katib is Kubernetes-native project for automated machine learning (AutoML).

Use Katib for automated tuning of your machine learning (ML) model's hyperparameters and architecture.

Katib is a Kubernetes-native project for automated machine learning (AutoML) —

it's a system for hyperparameter tuning and neural architecture search.

Katib supports a number of machine learning frameworks, including

TensorFlow, MXNet, PyTorch, XGBoost, and others.

The [Katib project](https://github.com/kubeflow/katib) is open source.

The [developer guide](https://github.com/kubeflow/katib/blob/master/docs/developer-guide.md)

is a good starting point for developers who want to contribute to the project.

8bitmp3 · 2020-11-10T20:25:57Z

@andreyvelich Thanks. If you're OK with the suggestions/own changes, feel free to get the LGTM and approve labels from the AutoML/Katib experts (which I am not 😄)

/assign @animeshsingh @Bobgy @joeliedtke
(approvers)

andreyvelich · 2020-11-10T21:31:07Z

@8bitmp3 Thank you again for the help on this PR!
If you don't have any other suggestions on the trial-template doc, I'll remove /hold label and we can merge this PR.

/cc @gaocegege @johnugeorge

8bitmp3 · 2020-11-10T23:15:54Z

@@ -1,13 +1,13 @@
 +++
 title = "Trial Template Overview"


Suggested change

title = "Trial Template Overview"

title = "Overview of trial template parameters in Katib"

(Sentence case, unless it's a product name, I think)

8bitmp3 · 2020-11-10T23:17:32Z

@@ -1,13 +1,13 @@
 +++
 title = "Trial Template Overview"
 description = "How to specify trial template parameters and support custom CRD in Katib"


Suggested change

description = "How to specify trial template parameters and support custom CRD in Katib"

description = "How to specify trial template parameters and support a custom resource (CRD) in Katib"

(I had to look up CRD on the K8s docs - correct me if I'm wrong. Just wanted to help some new users)

8bitmp3 · 2020-11-10T23:19:05Z

+in Katib. Follow this page to know more about changing trial template specification,
 how to use [Kubernetes ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/)
 to store templates and how to modify Katib controller to support your
 Kubernetes CRD in Katib experiments.


Suggested change

in Katib. Follow this page to know more about changing trial template specification,

how to use [Kubernetes ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/)

to store templates and how to modify Katib controller to support your

Kubernetes CRD in Katib experiments.

in Katib. You will learn about changing trial template specification,

how to use [Kubernetes ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/)

to store templates and how to modify Katib controller to support your

Kubernetes CRD in Katib experiments.

8bitmp3 · 2020-11-10T23:19:54Z

 (e.g. [Kubernetes `Deployment`](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/))
 as a trial worker without modifying Katib controller source code and building
-the new image. As long as your CRD creates Kubernetes pods, allows to inject
+the new image. As long as your CRD creates Kubernetes Pods, allows to inject


is it Pods or pods in K8s? I thought it's "pods" 😄

I think it's called Kubernetes Pods. 😄
Ref: https://kubernetes.io/docs/concepts/workloads/pods/#using-pods.

8bitmp3 · 2020-11-10T23:20:07Z

+the new image. As long as your CRD creates Kubernetes Pods, allows to inject
 the [sidecar container](https://kubernetes.io/docs/concepts/workloads/pods/) on
-these pods and has succeeded and failed status, you can use it in Katib.
+these Pods and has succeeded and failed status, you can use it in Katib.


Suggested change

these Pods and has succeeded and failed status, you can use it in Katib.

these Pods and has succeeded and failed status, you can use it in Katib.

is it Pods or pods in K8s? I thought it's "pods" 😄

8bitmp3 · 2020-11-10T23:20:40Z

 1. Modify Katib controller
   [ClusterRole's rules](https://github.com/kubeflow/katib/blob/master/manifests/v1beta1/katib-controller/rbac.yaml#L5)
-   with the new rule to get access for all resources that are created
+   with the new rule to give Katib access for the all resources that are created


Correction:

Suggested change

with the new rule to give Katib access for the all resources that are created

with the new rule to give Katib access to all resources that are created

8bitmp3 · 2020-11-10T23:20:57Z

   [ClusterRole's rules](https://github.com/kubeflow/katib/blob/master/manifests/v1beta1/katib-controller/rbac.yaml#L5)
-   with the new rule to get access for all resources that are created
+   with the new rule to give Katib access for the all resources that are created
   by trial. To know more about ClusterRole, check


"by the trial"?

8bitmp3 · 2020-11-10T23:21:27Z

@@ -293,7 +296,7 @@ Expected output for the Tekton `Pipeline`:
 ```

 If the above steps are successful, you are able to use your custom object YAML


Suggested change

If the above steps are successful, you are able to use your custom object YAML

If you ran the above steps successfully, you should be able to use your custom object YAML

8bitmp3

@andreyvelich Just took a last look at katib/trial-template.md. We can revise more stuff in another PR, if necessary. Let's try to get a LGTM and /approve soon. Thanks for the patience

andreyvelich · 2020-11-11T00:11:55Z

@andreyvelich Just took a last look at katib/trial-template.md. We can revise more stuff in another PR, if necessary. Let's try to get a LGTM and /approve soon. Thanks for the patience

Sure @8bitmp3.
/hold cancel
/approve

@gaocegege @johnugeorge Can you give your /lgtm please?

andreyvelich · 2020-11-11T01:04:59Z

I think we need to get /approve from one of the root OWNERS for this PR.
@animeshsingh @Bobgy @joeliedtke Can you help with it, please ?

Bobgy · 2020-11-11T08:59:09Z

@andreyvelich
Can stakeholders lgtm first? I can help with the approval.

Bobgy · 2020-11-11T08:59:34Z

/approve

k8s-ci-robot · 2020-11-11T08:59:44Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: andreyvelich, Bobgy

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [Bobgy]

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

rui-vas · 2020-11-11T10:30:16Z

/lgtm

rui-vas · 2020-11-11T10:37:23Z

Thank you @andreyvelich for this big push! It's merged 🚀

* Rename hyperparameter-tuning to Katib * Modify overview and hyperparameter * Modify docs for v1beta1 * Add v1beta1 REST api doc * Make metrics collector not capitalized * Add currentOptimalTrial info * Update UI images * Change describe to get command * Add v1alpha3 gRPC API ref * Add comments to v1alpha3 * Change REST to gRPC * Add default values for metrics collector * Change image tag to v1beta1-e294a90 * Changes after review * Fix list * Update v1beta1 reference * Add period * Add shell to commands * Fix colon * Address second review comments * Changes after doc check * Fix API links * Make changes for the trial template * Modify trial doc * Apply a11y rules * Address the comments * Changes for trial template guide * Trial template changes

k8s-ci-robot assigned gaocegege and johnugeorge Oct 26, 2020

k8s-ci-robot added the do-not-merge/work-in-progress label Oct 26, 2020

k8s-ci-robot requested review from 8bitmp3 and rui-vas October 26, 2020 17:31

k8s-ci-robot added the size/XXL label Oct 26, 2020

This was referenced Oct 27, 2020

Disable ephemeral storage in Katib Config #2315

Merged

Add Katib metric strategies info #2316

Merged

rui-vas reviewed Oct 28, 2020

View reviewed changes

andreyvelich mentioned this pull request Oct 28, 2020

Update Istio sidecar annotation information for the Katib experiments #2320

Merged

k8s-ci-robot requested review from gaocegege, johnugeorge and rui-vas October 28, 2020 21:07

This was referenced Oct 29, 2020

Default values for Katib Trials count #2321

Merged

Add resume policy instructions for Katib experiments #2324

Merged

Kubeflow 1.2 release doc changes #2322

Closed

Restructuring Kubeflow docs proposal kubeflow/community#440

Closed

rui-vas reviewed Oct 30, 2020

View reviewed changes

andreyvelich changed the title ~~[WIP] Katib v1beta1 documentation update~~ Katib v1beta1 documentation update Nov 2, 2020

k8s-ci-robot removed the do-not-merge/work-in-progress label Nov 2, 2020

8bitmp3 suggested changes Nov 2, 2020

View reviewed changes

8bitmp3 reviewed Nov 2, 2020

View reviewed changes

Comment thread content/en/docs/components/katib/overview.md Outdated

k8s-ci-robot assigned animeshsingh, Bobgy and joeliedtke Nov 10, 2020

Changes for trial template guide

f1d4c0a

8bitmp3 reviewed Nov 10, 2020

View reviewed changes

8bitmp3 suggested changes Nov 10, 2020

View reviewed changes

Trial template changes

bafe7b5

k8s-ci-robot removed the do-not-merge/hold label Nov 11, 2020

k8s-ci-robot added the approved label Nov 11, 2020

k8s-ci-robot assigned rui-vas Nov 11, 2020

k8s-ci-robot added the lgtm label Nov 11, 2020

k8s-ci-robot merged commit ba72604 into kubeflow:master Nov 11, 2020


		You can edit this Config Map even after deploying Katib.

		If you deploy Katib in Kubeflow namespace, to edit Katib config run this:

	If you deploy Katib in Kubeflow namespace, to edit Katib config run this:
	If you are deploying Katib in the Kubeflow namespace, run this command to edit your Katib config:


		All of these settings except `image` can be omitted. If you don't specify any other settings, default value is set.

		1. `image` - Docker image for the `File` metrics collector's container.

	1. `image` - Docker image for the `File` metrics collector's container.
	1. `image` - a Docker image for the `File` metrics collector's container.

		Katib is Kubernetes-native project for automated machine learning (AutoML).
		Use Katib for automated tuning of your machine learning (ML) model's hyperparameters and architecture.

	title = "Trial Template Overview"
	title = "Overview of trial template parameters in Katib"

	description = "How to specify trial template parameters and support custom CRD in Katib"
	description = "How to specify trial template parameters and support a custom resource (CRD) in Katib"

	these Pods and has succeeded and failed status, you can use it in Katib.
	these Pods and has succeeded and failed status, you can use it in Katib.

	with the new rule to give Katib access for the all resources that are created
	with the new rule to give Katib access to all resources that are created

		@@ -293,7 +296,7 @@ Expected output for the Tekton `Pipeline`:
		```

		If the above steps are successful, you are able to use your custom object YAML

	If the above steps are successful, you are able to use your custom object YAML
	If you ran the above steps successfully, you should be able to use your custom object YAML

Conversation

andreyvelich commented Oct 26, 2020

Uh oh!

kubeflow-bot commented Oct 26, 2020

Uh oh!

rui-vas commented Oct 28, 2020

Uh oh!

rui-vas left a comment

Choose a reason for hiding this comment

Uh oh!

andreyvelich commented Oct 28, 2020

Uh oh!

andreyvelich commented Oct 28, 2020

Uh oh!

andreyvelich commented Oct 28, 2020

Uh oh!

rui-vas left a comment

Choose a reason for hiding this comment

Uh oh!

rui-vas commented Oct 30, 2020

Uh oh!

andreyvelich commented Oct 30, 2020

Uh oh!

andreyvelich commented Nov 2, 2020

Uh oh!

8bitmp3 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andreyvelich Nov 2, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

8bitmp3 Nov 2, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

8bitmp3 commented Nov 10, 2020

Uh oh!

andreyvelich commented Nov 10, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andreyvelich Nov 11, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

8bitmp3 left a comment •

edited

Loading

andreyvelich Nov 2, 2020 •

edited

Loading

8bitmp3 Nov 2, 2020 •

edited

Loading

andreyvelich Nov 11, 2020 •

edited

Loading

Bobgy commented Nov 11, 2020 •

edited

Loading

rui-vas commented Nov 11, 2020 •

edited

Loading