Create a Quickstart to run a Tekton task with Minikube #298
Conversation
|
Taking a look today, give me a bit of time to read over this. |
|
My only question, is this to show off Tekton inside of KiND? Otherwise I'm not seeing the advantage of this over https://tekton.dev/docs/getting-started/pipelines/ |
There was a problem hiding this comment.
Very cool!! I was able to run through it myself so easily (i might be not quite the target audience tho haha - BUT ive never really used KIND before so that was pretty cool for me!)
Couple of thoughts:
- This is kind of a nit but I'm wondering if we want to have this repo as the source of truth for this quickstart - it seems like it's only using Tekton Pipelines, would it make sense to store it (and potentially version and update it) alongside the Tekton Pipelines docs? (maybe it could even replace the tutorial over there?)
- What do you think about updating or maybe replacing the existing getting started landing page? (https://tekton.dev/docs/getting-started/) (seems like this kind tutorial would be a good replacement?)
|
|
||
| ## Create and run a basic Task | ||
|
|
||
| A **Taks** defines a series of **steps** that run sequentially to perform some |
| command: | ||
| - echo | ||
| args: | ||
| - "Hello World" |
There was a problem hiding this comment.
there's something odd about the indentation here - i think it's way to deep (2 spaces would probably be good, or 4 at most?) and it shows up as red in the preview 🤔
There was a problem hiding this comment.
I think these were tabs instead of spaces (?). This looked fine on my computer :). I made sure they were converted to spaces, I think it's fixed now.
| spec: | ||
| taskRef: | ||
| name: echo-hello-world | ||
| ``` |
There was a problem hiding this comment.
probably makes sense to use TaskRuns explicitly but just so you know there's one other option that might be a nice user experience - but the user would have to also install tkn (https://github.com/tektoncd/cli) so maybe it's not worth the extra setup - but if it wasn't too much trouble, instead of making a TaskRun here the user could do tkn task start echo-hello-world
There was a problem hiding this comment.
I thought about it, same to check the task status. The trade-off of using a simpler command but having to install something extra, if this is your first ever experience with tekton, may not be worth it in my opinion. For the longer tutorial covering pipelines in more detail it's definitely a good idea to ask for the tkn client prerequisite.
| ... | ||
| </pre> | ||
|
|
||
| The line `Status: Succeeded` confirms that TaskRun completed with no errors. |
There was a problem hiding this comment.
instead of showing them the pod, it might be a bit nicer to show them the taskrun, e.g. kubectl --context kind-tektoncd get taskrun echo-hello-world-task-run would show something simple like:
NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME
echo-hello-world-task-run True Succeeded 22h 22h
plus the pods are (kind of) an implementation detail of tekton anyway 🤞 (tho in reality is not like ppl can really ignore them...)
|
@jjasghar i think what's really nice about using kind is that it's very easy to setup and lets us have getting started instructions that are pretty cloud agnostic (but still tell you how to setup the cluster in the first place!) my understanding is that this tutorial would replace at least 1 (if not more - we have some duplication going on) of our existing tutorials. the one you linked to (https://tekton.dev/docs/getting-started/pipelines/) i think is meant to build on a previous task based tutorial and add pipelines? (presumably it would work on the kind cluster as well? maybe needs a few updates to flow nicely from the kind tutorial). i think this tutorial would probably replace https://tekton.dev/docs/getting-started/ (maybe we go back to our old approach and have a tab or something for the openshift specific instructions?) |
|
@jjasghar This is intended to be the very first Tekton doc for someone with no prior experience. A 5-minute task that is easy to complete so you get that "feels good" moment that you need to explore further. That's why it's prescriptive about Kind, it's an effort to guarantee the task can be completed successfully with minimal effort. The existing getting started requires some cognitive work to follow. @bobcatfish You are correct, my intention is to consolidate the doc in the pipelines repo (https://github.com/tektoncd/pipeline/blob/main/docs/tutorial.md), the 2 getting started docs from tekton.dev (getting-started and getting-started/pipelines), and the Katacoda tuto (https://github.com/tektoncd/website/tree/main/tutorials/katacoda/getting-started) in to a single doc that we can link from everywhere. The quickstart in his PR being the entry point and a further more in-depth doc as the natural follow-up. I'm going to take a look at the other comments and apply the fixes later this week. Thanks for the feedback. |
|
Thanks @geriom - I haven't reviewed the instructions in details yet - but I definitely support using |
If we move it to that repo it would be harder to make it a landing page because of how the sync script works.
I like the idea. Should I proceed and move the current content to a different file? |
😨 well maybe in the meantime we could link directly to the page on tekton.dev from the pipelines repo :S
I'd remove the existing file entirely - in the end I think our docs at tekton.dev should be pretty authorative vs. kind of a grab bag of different tutorials. The tutorial will also still be in version control if someone wants to resurrect it later. |
|
... did not mean to hit that button |
|
TOO MUCH POWER |
|
/approve also going to ping @jjasghar and @afrittoli to make sure they have no objections |
That's very cool! I will add this to the longer tutorial as a quick way to set everything up. |
There was a problem hiding this comment.
Thanks for this.
The quickstart looks fine, but it overlaps with the existing "getting started" home page quite a bit. So we would have two pages giving slightly different version of the same basic information:
- install kind
- installed tekton via the release file and wait for completion
- install a task and run it
Can we converge the two pages into one? Could we change this PR into updating the existing page instead of adding a new one?
The existing one includes out of date versions of k8s which needs to be updated.
If you'd like to keep the page simple, we could replace the "persistent volumes" section with a link to https://tekton.dev/docs/pipelines/install/ for details info about configuring Tekton.
The info about installing the CLI, while valuable, is duplicated from https://tekton.dev/docs/cli/, so we could include a link to that instead.
I already thought about this for some time, I have a couple of ideas. I will write a draft and update the PR in the next couple of days so you can take a look. Thanks for the feedback. |
|
/hold |
|
Waiting for the doc plan to be agreed on, then we can resume this one and get it merged |
|
@afrittoli This PR is ready to be merged after a a second round of reviews. Updates: I switched from Kind to Minikube because of the recent changes in the Docker licence. With Minikube the users can pick a different engine and are not forced to use docker to follow the instructions. I also added a second page, this is now a two-part tutorial, somewhat mirroring the content we had before:
I also deleted the original tutorial that we had in |
|
Looks like this removes reference to the nightly releases. It would be good to restore that as we do want to make them more visible. Ref: #344 (comment) |
|
In the spirit of the new guidelines for tutorials, I think we should pick just one path and go with it throughout the entire doc, don't cover alternatives in the getting started. Instead, I would prefer to create an installation doc, that covers all the available installation options. Edit: Just opened an issue to track this. |
There was a problem hiding this comment.
very nice!!! just some minor comments from me, that was very smooth for me (and the first time ive used minikube in... years XD might do it more often now!)
(i'm going to hold off on doing an approve or lgtm and defer to folks that have been attending the docs WG but lemme know if I need to)
There was a problem hiding this comment.
Thanks for this - I added some cosmetic comments that needs to be fixed before this is merged, but the content looks great.
Historically with always been starting our Tekton guides with writing your own Task and Pipeline... I wonder however if we could rethink that as an "advanced" step - and start with using Tasks from the catalog instead? Not something for this PR, but I wanted to bring up the idea. @tektoncd/core-maintainers thoughts?
that could make a lot of sense @afrittoli - could get users much more quickly to the satisfaction of running something and having it work :D |
|
Completely agree with both of you @bobcatfish and @afrittoli . I'm going to give it some thought and share my ideas in either the WG or the mailing list. |
|
@geriom @AlanGreene I kicked off a re-deploy now, but it did not help - I still see the same cosmetic glitches in the rendering. I think this needs to be rebased so we can preview the actual result. Apart from that the content looks good to me, so feel free to merge once the cosmetic issues are fixed |
15f59d5 to
b0c9678
Compare
|
@afrittoli I rebased the branch, the preview looks fine now. @AlanGreene I think we can merge it. |
Introductory guide for newcomers. This is a two-file quickstart that shows a simple example to create a task and a pipeline. These tutorials do not include new information. The information here is reorganized to be easier to understand for newcomers. Including prescritpive steps that the user just has to copy/paste .
|
In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: AlanGreene, bobcatfish 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 |
Changes
Introductory guide friendly for newcomers. The approach in this doc is to be
easier to follow by providing prescriptive instructions about the tools
to use. After installing the prerequisites, doing copy/paste of the code
samples should work.
Submitter Checklist
These are the criteria that every PR should meet, please check them off as you
review them:
See the contribution guide
for more details.