Create minimal usage example for the Pipelines API #1688
Conversation
fediazgon
force-pushed
the
734-pipelines-api-example
branch
from
ecac8c2 to
9ae8744
Compare
sarahmaddox
added
the
doc-sprint
|
/assign @joeliedtke |
| @@ -0,0 +1,69 @@ | |||
| +++ | |||
| title = "Experiment with the Pipelines API" | |||
There was a problem hiding this comment.
Experiment with the Pipelines API -> Experiment with the Kubeflow Pipelines API
| description = "Get started with the Kubeflow Pipelines API" | ||
| weight = 1 | ||
| +++ | ||
|
|
There was a problem hiding this comment.
Suggestion: It is a good practice to give readers an overview of what they will learn in a tutorial. Consider adding an overview like the following:
This tutorial demonstrates how to use the Kubeflow Pipelines API to build, run, and manage pipelines. This guide is recommended for users who would like to learn how to manage Kubeflow Pipelines using the REST API.
|
|
||
| ## Before you start | ||
|
|
||
| This tutorial assumes that you have access to the `ml-pipeline` service. If you didn’t configure Kubeflow to integrate with an identity provider, then you can port-forward directly to the service: |
There was a problem hiding this comment.
Suggested revision: If you didn’t configure Kubeflow to integrate with an identity provider, then you can port-forward directly to the service:
Update to:
If Kubeflow is not configured to use an identity provider, use port-forwarding to directly access the service:
| kubectl port-forward -n kubeflow svc/ml-pipeline ${SVC_PORT}:8888 | ||
| ``` | ||
|
|
||
| For this tutorial, we are going to assume that the service is accessible in localhost. |
There was a problem hiding this comment.
Generally it is good to avoid "we" unless providing an opinion on behalf of the Kubeflow project. How about this:
This tutorial assumes that the service is accessible on localhost.
|
|
||
| ## Building and running a pipeline | ||
|
|
||
| In this example, similarly to the [Experiment with the Pipelines Samples](/docs/pipelines/tutorials/build-pipeline/) tutorial, we are going to download and compile the |
There was a problem hiding this comment.
Suggested revision to avoid "we":
Follow this guide to download, compile, and run the [`sequential.py` sample pipeline](https://github.com/kubeflow/pipelines/blob/master/samples/core/sequential/sequential.py). To learn how to compile and run pipelines using the Kubeflow Pipelines SDK or a Jupyter notebook, follow the [experimenting with Kubeflow Pipelines samples tutorial](/docs/pipelines/tutorials/build-pipeline/).
| EOF | ||
| ) | jq -r .run.id) | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Suggestion: Would it be helpful for users to have an example of what a successful return value looks like? For example:
The response should be something like this:
example response
There was a problem hiding this comment.
I've added the response in the following command since it is the same. It also simplifies the command since otherwise I would need to do something like | jq | tee > dev/tty | jq -r .run.id to both save the output and show the response.
| ``` | ||
| curl ${SVC}/apis/v1beta1/runs/${RUN_ID} | jq | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Suggestion: Would it be helpful for users to have an example of what a successful return value looks like? For example:
The response should be something like this:
example response
| curl ${SVC}/apis/v1beta1/pipelines/${PIPELINE_ID} | jq | ||
| ``` | ||
|
|
||
| Then, you can trigger a run using the obtained id. |
There was a problem hiding this comment.
Suggested revision:
Use the PIPELINE_ID to trigger a run of your pipeline.
| ) | jq -r .run.id) | ||
| ``` | ||
|
|
||
| After a while, the status of your pipeline should change to "Succeeded". |
There was a problem hiding this comment.
Suggested revision:
Run the following command occasionally to see how the status of your run changes. After a while, the status of your pipeline should change to **Succeeded**.
| curl ${SVC}/apis/v1beta1/runs/${RUN_ID} | jq | ||
| ``` | ||
|
|
||
| Please, take a look at the [Kubeflow Pipelines API Reference](docs/pipelines/reference/api/kubeflow-pipeline-api-spec/) for more information about how to use the API. |
There was a problem hiding this comment.
Suggested revision(avoiding "please"):
Read the Kubeflow Pipelines API Reference to learn more about how to use the API.
fediazgon
force-pushed
the
734-pipelines-api-example
branch
2 times, most recently
from
f88bdb5 to
dfccf7c
Compare
fediazgon
force-pushed
the
734-pipelines-api-example
branch
from
dfccf7c to
18a8023
Compare
|
Thanks for the thorough review @joeliedtke. Please, have another look. |
|
/lgtm This is great, thanks for adding this tutorial! |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: joeliedtke The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
This fixes #734.
Preview at https://deploy-preview-1688--competent-brattain-de2d6d.netlify.com/docs/pipelines/tutorials/api-pipelines/
The tutorial could be easily expanded by adding a section on "How to associate a run with an experiment". But I think this one is a good start.
This change is