clarify in docs to not use apiVersion for taskRef for non-customtask #6704

Yongxuanzhang · 2023-05-23T17:56:21Z

Changes

This commit closes #6682. When apiversion and kind are both set for
task, it is also considered to be a custom task. If users want to refer
to tasks or cluster tasks, apiVersion shouldn't be set. This commit
clarify this in the docs.

/kind bug

Signed-off-by: Yongxuan Zhang [email protected]

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

Has Docs if any changes are user facing, including updates to minimum requirements e.g. Kubernetes version bumps
Has Tests included if any functionality added or changed
Follows the commit message standard
Meets the Tekton contributor standards (including functionality, content, code)
Has a kind label. You can add one by adding a comment on this PR that contains /kind <type>. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tep
Release notes block below has been updated with any user facing changes (API changes, bug fixes, changes requiring upgrade notices or deprecation warnings). See some examples of good release notes.
Release notes contains the string "action required" if the change requires additional action from users switching to the new release

Release Notes

NONE

tekton-robot · 2023-05-23T17:56:23Z

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

Yongxuanzhang · 2023-05-23T17:57:43Z

pkg/apis/pipeline/v1beta1/pipeline_types.go

@@ -224,7 +224,7 @@ type PipelineTask struct {
 func (et *EmbeddedTask) IsCustomTask() bool {
 	// Note that if `apiVersion` is set to `"tekton.dev/v1beta1"` and `kind` is set to `"Task"`,
 	// the reference will be considered a Custom Task - https://github.com/tektoncd/pipeline/issues/6457
-	return et != nil && et.APIVersion != "" && et.Kind != ""
+	return et != nil && et.APIVersion != "" && et.Kind != "" && et.Kind != string(ClusterTaskKind)


I wonder if checking (et.APIVersion!="v1beta1"&&et.Kind != string(ClusterTaskKind)) would be better?

ah don't think we should handle ClusterTask differently from Task -- maybe what we need is better documentation?

Yongxuanzhang · 2023-05-23T17:58:13Z

/assign @jerop

lbernick

Can you please add some pipelinerun reconciler unit tests for this change? It might be beneficial to have e2e tests as well but we can start with reconciler tests

jerop

maybe what we need is better documentation that if apiversion and kind are set, we will create a customrun -- #6457

jerop · 2023-05-23T19:40:12Z

pkg/apis/pipeline/v1beta1/pipeline_types.go

@@ -224,7 +224,7 @@ type PipelineTask struct {
 func (et *EmbeddedTask) IsCustomTask() bool {
 	// Note that if `apiVersion` is set to `"tekton.dev/v1beta1"` and `kind` is set to `"Task"`,
 	// the reference will be considered a Custom Task - https://github.com/tektoncd/pipeline/issues/6457
-	return et != nil && et.APIVersion != "" && et.Kind != ""
+	return et != nil && et.APIVersion != "" && et.Kind != "" && et.Kind != string(ClusterTaskKind)


ah don't think we should handle ClusterTask differently from Task -- maybe what we need is better documentation?

lbernick · 2023-05-23T19:52:02Z

From the linked issue, it sounds like this used to create TaskRuns instead of CustomRuns, and this was a regression when updating to v0.44. If you can't specify "ClusterTask" as the "kind" in a TaskRef, how would you specify a cluster task?

jerop · 2023-05-23T20:58:04Z

To clarify, you can create a "ClusterTask" with "kind" in TaskRef -- you just can't put APIVersion as well because that creates a CustomRun -- the user removed APIVersion and this resolved their issue

Yongxuanzhang · 2023-05-23T21:01:09Z

Yes, I wonder if we need to fix it in code so users can still use apiversion+kind for cluster tasks?
Or we need to document and also tell users that you shouldn't use apiversion+kind for cluster task or tasks if you want to use them normally.
It seems that this is an hidden issue but triggered by we enable the custom task by default

jerop · 2023-05-23T21:05:57Z

I think we should document instead of changing the implementation because some users are relying on apiversion and kind being set to create customruns -- #6457

If we make an exception for "ClusterTask", would we do the same for "Task" and "Pipeline"? What about the Custom Task controllers that depend on the existing behavior, such as Pipeline in Pipeline Custom Task?

jerop · 2023-05-23T21:08:14Z

@Yongxuanzhang please update the commit and PR with more context, including #6459, #6505, #6457

Yongxuanzhang · 2023-05-23T21:33:17Z

What confused me is the "apiversion", if it is only used for custom tasks, and we don't use it for cluster task, tasks (since the storage version in the cluster is fixed, it is not possible to refer v1 tasks and v1beta1 tasks in the same cluster), we do need to clarify it to users (docs or even rename it)

I lean to update the docs to clarify it now, since there's no need to use "apiversion"+"kind" for cluster tasks and tasks, pipelines. Though we do support it in previous versions when the custom task is not enabled by default and we should have called this out to users when we introduced this change.

lbernick · 2023-05-24T13:30:15Z

To clarify, you can create a "ClusterTask" with "kind" in TaskRef -- you just can't put APIVersion as well because that creates a CustomRun -- the user removed APIVersion and this resolved their issue

Ah sorry, I missed that. However, it does still sound like the user experienced different behavior for existing CRDs when upgrading. @Yongxuanzhang I'm curious why you say this might have started happening when we enabled custom tasks by default?

I agree with Yongxuan that if we only use APIVersion for custom tasks, it would be nice to rename it in some way. (We can't remove it but can add a new field and document that instead.)

I still find it confusing that "kind=Task" or ClusterTask, Pipeline, etc creates a custom task when apiversion is used :( but I'm ok with improving docs for now

Yongxuanzhang · 2023-05-24T14:29:43Z

To clarify, you can create a "ClusterTask" with "kind" in TaskRef -- you just can't put APIVersion as well because that creates a CustomRun -- the user removed APIVersion and this resolved their issue

Ah sorry, I missed that. However, it does still sound like the user experienced different behavior for existing CRDs when upgrading. @Yongxuanzhang I'm curious why you say this might have started happening when we enabled custom tasks by default?

I agree with Yongxuan that if we only use APIVersion for custom tasks, it would be nice to rename it in some way. (We can't remove it but can add a new field and document that instead.)

I still find it confusing that "kind=Task" or ClusterTask, Pipeline, etc creates a custom task when apiversion is used :( but I'm ok with improving docs for now

Previously, if custom task is not enabled, users can use apiversion+task/clustertask in taskref to refer tasks, but after we enabled it by default, the taskref will be considered as a custom task and creates customrun instead of taskrun

tekton-robot · 2023-05-24T15:34:49Z

@Yongxuanzhang: The label(s) kind/cancel cannot be applied, because the repository doesn't have them.

In response to this:

/kind bug cancel

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.

tekton-robot · 2023-05-24T15:35:08Z

@Yongxuanzhang: The label(s) kind/remove cannot be applied, because the repository doesn't have them.

In response to this:

/kind bug remove

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.

Yongxuanzhang · 2023-05-24T15:36:58Z

/remove-kind bug

lbernick · 2023-05-24T15:58:19Z

Yongxuan can you check if we have any examples in the docs that use APIVersion for TaskRefs that aren't custom tasks?

Yongxuanzhang · 2023-05-24T16:09:35Z

Yongxuan can you check if we have any examples in the docs that use APIVersion for TaskRefs that aren't custom tasks?

I cannot find any examples in docs, but found one in unit tests, just removed it

lbernick · 2023-05-24T16:11:33Z

Thanks, this lgtm, just two quick suggestions:

This is a docs update, so I don't think it needs a release note
Let's update the custom run docs to specify that a non-empty api version will always create a customrun, and apiversion is for customruns only

lbernick

I think you may need to update the PR description

docs/pipelines.md

This commit closes tektoncd#6682. When apiversion and kind are both set for task, it is also considered to be a custom task. If users want to refer to tasks or cluster tasks, apiVersion shouldn't be set. This commit clarify this in the docs. Signed-off-by: Yongxuan Zhang [email protected]

jerop

/lgtm

tekton-robot · 2023-05-25T17:46:02Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jerop, lbernick

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:

~~OWNERS~~ [jerop,lbernick]

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

tekton-robot added release-note Denotes a PR that will be considered when it comes time to generate release notes. kind/bug Categorizes issue or PR as related to a bug. do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. labels May 23, 2023

tekton-robot requested review from vdemeester and wlynch May 23, 2023 17:56

tekton-robot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label May 23, 2023

Yongxuanzhang commented May 23, 2023

View reviewed changes

Yongxuanzhang marked this pull request as ready for review May 23, 2023 17:57

tekton-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label May 23, 2023

tekton-robot requested review from abayer and jerop May 23, 2023 17:58

tekton-robot assigned jerop May 23, 2023

lbernick reviewed May 23, 2023

View reviewed changes

Yongxuanzhang force-pushed the fix-6682 branch from 744bd77 to 45569eb Compare May 23, 2023 19:38

tekton-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels May 23, 2023

Yongxuanzhang force-pushed the fix-6682 branch from 45569eb to b7806f4 Compare May 23, 2023 19:42

jerop reviewed May 23, 2023

View reviewed changes

Yongxuanzhang mentioned this pull request May 23, 2023

ClusterTask creates CustomRun (v0.41.1 -> v0.44.2) #6682

Closed

Yongxuanzhang force-pushed the fix-6682 branch from b7806f4 to fd68c15 Compare May 24, 2023 15:14

tekton-robot added the kind/documentation Categorizes issue or PR as related to documentation. label May 24, 2023

tekton-robot removed the kind/bug Categorizes issue or PR as related to a bug. label May 24, 2023

lbernick self-assigned this May 24, 2023

Yongxuanzhang changed the title ~~cluster task is not custom task~~ clarify in docs to not use apiVersion for taskRef for non-customtask May 24, 2023

Yongxuanzhang force-pushed the fix-6682 branch from 0581f9d to 3af3578 Compare May 24, 2023 16:09

tekton-robot added release-note-none Denotes a PR that doesnt merit a release note. and removed release-note Denotes a PR that will be considered when it comes time to generate release notes. labels May 24, 2023

Yongxuanzhang force-pushed the fix-6682 branch from 3af3578 to 1ef3ab7 Compare May 24, 2023 16:34

tekton-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels May 24, 2023

Yongxuanzhang force-pushed the fix-6682 branch from 1ef3ab7 to d673584 Compare May 24, 2023 16:35

tekton-robot added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels May 24, 2023

Yongxuanzhang requested review from lbernick and jerop May 24, 2023 17:42

lbernick reviewed May 25, 2023

View reviewed changes

docs/pipelines.md Outdated Show resolved Hide resolved

Yongxuanzhang force-pushed the fix-6682 branch from 18be458 to aa15963 Compare May 25, 2023 15:44

lbernick approved these changes May 25, 2023

View reviewed changes

tekton-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label May 25, 2023

jerop approved these changes May 25, 2023

View reviewed changes

tekton-robot added the lgtm Indicates that a PR is ready to be merged. label May 25, 2023

tekton-robot merged commit a1036ad into tektoncd:main May 25, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

clarify in docs to not use apiVersion for taskRef for non-customtask #6704

clarify in docs to not use apiVersion for taskRef for non-customtask #6704

Yongxuanzhang commented May 23, 2023 •

edited

Loading

tekton-robot commented May 23, 2023

Yongxuanzhang May 23, 2023 •

edited

Loading

jerop May 23, 2023

Yongxuanzhang commented May 23, 2023

lbernick left a comment

jerop left a comment

jerop May 23, 2023

lbernick commented May 23, 2023

jerop commented May 23, 2023

Yongxuanzhang commented May 23, 2023

jerop commented May 23, 2023

jerop commented May 23, 2023 •

edited

Loading

Yongxuanzhang commented May 23, 2023 •

edited

Loading

lbernick commented May 24, 2023 •

edited

Loading

Yongxuanzhang commented May 24, 2023

tekton-robot commented May 24, 2023

tekton-robot commented May 24, 2023

Yongxuanzhang commented May 24, 2023

lbernick commented May 24, 2023

Yongxuanzhang commented May 24, 2023

lbernick commented May 24, 2023

lbernick left a comment

jerop left a comment

tekton-robot commented May 25, 2023

clarify in docs to not use apiVersion for taskRef for non-customtask #6704

clarify in docs to not use apiVersion for taskRef for non-customtask #6704

Conversation

Yongxuanzhang commented May 23, 2023 • edited Loading

Changes

Submitter Checklist

Release Notes

tekton-robot commented May 23, 2023

Yongxuanzhang May 23, 2023 • edited Loading

Choose a reason for hiding this comment

jerop May 23, 2023

Choose a reason for hiding this comment

Yongxuanzhang commented May 23, 2023

lbernick left a comment

Choose a reason for hiding this comment

jerop left a comment

Choose a reason for hiding this comment

jerop May 23, 2023

Choose a reason for hiding this comment

lbernick commented May 23, 2023

jerop commented May 23, 2023

Yongxuanzhang commented May 23, 2023

jerop commented May 23, 2023

jerop commented May 23, 2023 • edited Loading

Yongxuanzhang commented May 23, 2023 • edited Loading

lbernick commented May 24, 2023 • edited Loading

Yongxuanzhang commented May 24, 2023

tekton-robot commented May 24, 2023

tekton-robot commented May 24, 2023

Yongxuanzhang commented May 24, 2023

lbernick commented May 24, 2023

Yongxuanzhang commented May 24, 2023

lbernick commented May 24, 2023

lbernick left a comment

Choose a reason for hiding this comment

jerop left a comment

Choose a reason for hiding this comment

tekton-robot commented May 25, 2023

Yongxuanzhang commented May 23, 2023 •

edited

Loading

Yongxuanzhang May 23, 2023 •

edited

Loading

jerop commented May 23, 2023 •

edited

Loading

Yongxuanzhang commented May 23, 2023 •

edited

Loading

lbernick commented May 24, 2023 •

edited

Loading