diff --git a/README.md b/README.md index 81fb383f922..29f45193570 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ A Suggestion is an algorithm to construct a parameter set. Currently Katib suppo ## Components in Katib Katib consists of several components as shown below. Each component is running on k8s as a deployment. -Each component communicates with others via GRPC and the API is defined at `pkg/api/api.proto`. +Each component communicates with others via GRPC and the API is defined at `pkg/api/v1alpha1/api.proto`. - vizier: main components. - vizier-core : API server of vizier. @@ -78,19 +78,19 @@ Each component communicates with others via GRPC and the API is defined at `pkg/ ## Getting Started -Please see [README.md](./examples/README.md) for more details. +Please see [README.md](./examples/v1alpha1/README.md) for more details. ## Web UI Katib provides a Web UI. You can visualize general trend of Hyper parameter space and each training history. You can use -[random-example](https://github.com/kubeflow/katib/blob/master/examples/random-example.yaml) or -[other examples](https://github.com/kubeflow/katib/blob/master/examples) to generate a similar UI. +[random-example](https://github.com/kubeflow/katib/blob/master/examples/v1alpha1/random-example.yaml) or +[other examples](https://github.com/kubeflow/katib/blob/master/examples/v1alpha1) to generate a similar UI. ![katibui](https://user-images.githubusercontent.com/10014831/48778081-a4388b80-ed17-11e8-938b-fc59a5d2e574.gif) ## API Documentation -Please refer to [api.md](./pkg/api/gen-doc/api.md). +Please refer to [api.md](./pkg/api/v1alpha1/gen-doc/api.md). ## Quickstart to run tfjob and pytorch operator jobs in Katib @@ -158,7 +158,7 @@ spec: Create this pv after deploying Katib package ``` -kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/manifests/pv/pv.yaml +kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/manifests/v1alpha1/pv/pv.yaml ``` ### Running examples @@ -189,21 +189,21 @@ spec: If you are not using GKE and you don't have StorageClass for dynamic volume provisioning at your cluster, you have to create pvc and pv ``` -kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/examples/tfevent-volume/tfevent-pvc.yaml +kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/examples/v1alpha1/tfevent-volume/tfevent-pvc.yaml -kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/examples/tfevent-volume/tfevent-pv.yaml +kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/examples/v1alpha1/tfevent-volume/tfevent-pv.yaml ``` This is example for tfjob operator ``` -kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/examples/tfjob-example.yaml +kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/examples/v1alpha1/tfjob-example.yaml ``` This is example for pytorch operator ``` -kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/examples/pytorchjob-example.yaml +kubectl create -f https://raw.githubusercontent.com/kubeflow/katib/master/examples/v1alpha1/pytorchjob-example.yaml ``` You can check status of StudyJob @@ -359,7 +359,7 @@ ks delete ${KF_ENV} -c tf-job-operator If you create pv for Katib, delete it ``` -kubectl delete -f https://raw.githubusercontent.com/kubeflow/katib/master/manifests/pv/pv.yaml +kubectl delete -f https://raw.githubusercontent.com/kubeflow/katib/master/manifests/v1alpha1/pv/pv.yaml ``` If you deploy Ambassador, delete it diff --git a/docs/developer-guide.md b/docs/developer-guide.md index fff36055665..d5f6d36d6b6 100644 --- a/docs/developer-guide.md +++ b/docs/developer-guide.md @@ -17,12 +17,12 @@ dep ensure --vendor-only You can build all images from source. ```bash -./scripts/build.sh +./scripts/v1alpha1/build.sh ``` ## Implement new suggestion algorithm -Suggestion API is defined as GRPC service at `pkg/api/api.proto`. Source code is [here](https://github.com/kubeflow/katib/blob/master/pkg/api/api.proto). You can attach new algorithm easily. +Suggestion API is defined as GRPC service at `pkg/api/v1alpha1/api.proto`. Source code is [here](https://github.com/kubeflow/katib/blob/master/pkg/api/v1alpha1/api.proto). You can attach new algorithm easily. - implement suggestion API - make k8s service named vizier-suggestion-{ algorithm-name } and expose port 6789 diff --git a/docs/rest-api.md b/docs/rest-api.md index 591d7fb9257..0da9cc43063 100644 --- a/docs/rest-api.md +++ b/docs/rest-api.md @@ -1,6 +1,6 @@ -## REST API +## REST API -For each RPC service, we define an equivalent HTTP REST API method using [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway). The mapping between service and REST API method can be found in this [file](https://github.com/kubeflow/katib/blob/master/pkg/api/api.proto). The mapping includes the URL path, query parameters and request body. You can read more details on the supported methods and binding options at this [link](https://cloud.google.com/service-infrastructure/docs/service-management/reference/rpc/google.api#http) +For each RPC service, we define an equivalent HTTP REST API method using [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway). The mapping between service and REST API method can be found in this [file](https://github.com/kubeflow/katib/blob/master/pkg/api/v1alpha1/api.proto). The mapping includes the URL path, query parameters and request body. You can read more details on the supported methods and binding options at this [link](https://cloud.google.com/service-infrastructure/docs/service-management/reference/rpc/google.api#http) ## Examples diff --git a/examples/v1alpha1/README.md b/examples/v1alpha1/README.md index 403f2b0b3fc..cd2f009fac3 100644 --- a/examples/v1alpha1/README.md +++ b/examples/v1alpha1/README.md @@ -199,7 +199,7 @@ The templates are defined in [ConfigMap](./workerConfigMap.yaml). There are two templates: defaultWorkerTemplate.yaml and gpuWorkerTemplate.yaml. You can add your template for worker. Then you should specify the template in your studyjob spec. -[This example](/examples/gpu-example.yaml) uses `gpuWorkerTemplate.yaml`. +[This example](/examples/v1alpha1/gpu-example.yaml) uses `gpuWorkerTemplate.yaml`. You can apply it same as other examples. ``` $ kubectl apply -f gpu-example.yaml @@ -369,7 +369,7 @@ batch2 accuracy=0.8 Validation-accuracy=0.75 ``` The metrics collector will collect all logs of metrics. -The manifest of metrics collector is also generated from template and defined [here](/manifests/studyjobcontroller/metricsControllerConfigMap.yaml). +The manifest of metrics collector is also generated from template and defined [here](/manifests/v1alpha1/studyjobcontroller/metricsControllerConfigMap.yaml). You can add your template and specify `spec.metricsCollectorSpec.metricsCollectorTemplatePath` in a studyjob manifest. ### TF Event File Metrics Collector diff --git a/pkg/api/README.md b/pkg/api/README.md index dce7b5d8305..6bafe5a4289 100644 --- a/pkg/api/README.md +++ b/pkg/api/README.md @@ -5,9 +5,16 @@ Suggestion service is an API for Suggestion services. EarlyStopping service is an API for EarlyStopping services. ## Documentation -Please refer to [api.md](./gen-doc/api.md). +Please refer to the `api.md`: + * [v1alpha1 documentation](./v1alpha1/gen-doc/api.md) + * [v1alpha2 documentation](./v1alpha2/gen-doc/api.md) ## Update API and generate documents -When you want to edit API, please only edit [api.proto](./api.proto) and generate other file from it. -Documents are also generated from [api.proto](./api.proto) by [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc). -By [build.sh](./build.sh), you can update every file from api.proto and generate docs. +When you want to edit the API, please only edit the corresponding `api.proto` and generate other files from it: + * [v1alpha1/api.proto](./v1alpha1/api.proto) + * [v1alpha2/api.proto](./v1alpha2/api.proto) + +Documents are also generated from `api.proto` by [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc). +Running `build.sh` can update every file from `api.proto` and generate docs: + * [v1alpha1/build.sh](./v1alpha1/build.sh) + * [v1alpha2/build.sh](./v1alpha2/build.sh)