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

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]
Yongxuanzhang · May 24, 2023 · 1ef3ab7 · 1ef3ab7
1 parent 96212a1
commit 1ef3ab7
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 34 deletions.
diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -279,6 +279,8 @@ tasks:
       name: build-push
 ```
 
+**Note:** Using both `apiVersion` and `kind` will create [CustomRun](customruns.md), don't set `apiVersion` if only referring to [`Task`](tasks.md).
+
 or
 
 ```yaml
@@ -1537,7 +1539,7 @@ that is responsible for watching and updating `CustomRun`s which reference their
 ### Specifying the target Custom Task
 
 To specify the custom task type you want to execute, the `taskRef` field
-must include the custom task's `apiVersion` and `kind` as shown below:
+must include the custom task's `apiVersion` and `kind` as shown below, `apiVersion` is only used to create `CustomRun`:
 
 ```yaml
 spec:

diff --git a/docs/taskruns.md b/docs/taskruns.md
@@ -91,6 +91,7 @@ spec:
     name: read-task
 ```
 
+
 You can also embed the desired `Task` definition directly in the `TaskRun` using the `taskSpec` field:
 
 ```yaml
@@ -302,10 +303,10 @@ status:
     reason: Succeeded
     status: "True"
     type: Succeeded
-  ... 
+  ...
   steps:
   - container: step-default
-    ...  
+    ...
   taskSpec:
     steps:
     - image: ubuntu
@@ -426,13 +427,13 @@ spec:
 apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
 kind: TaskRun
 metadata:
-  name: taskrun 
+  name: taskrun
 spec:
   taskRef:
     name: task
   computeResources:
     requests:
-      cpu: 1 
+      cpu: 1
     limits:
       cpu: 2
 ```
@@ -512,21 +513,21 @@ workspaces down to other inlined resources.
 **Workspace substutions will only be made for `commands`, `args` and `script` fields of `steps`, `stepTemplates`, and `sidecars`.**
 
 ```yaml
-apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1 
-kind: TaskRun                  
+apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
+kind: TaskRun
 metadata:
   generateName: propagating-workspaces-
 spec:
-  taskSpec:                    
-    steps:                     
-      - name: simple-step      
-        image: ubuntu          
-        command:               
-          - echo               
-        args:                  
+  taskSpec:
+    steps:
+      - name: simple-step
+        image: ubuntu
+        command:
+          - echo
+        args:
           - $(workspaces.tr-workspace.path)
-  workspaces:                  
-  - emptyDir: {}               
+  workspaces:
+  - emptyDir: {}
     name: tr-workspace
 ```
 
@@ -552,32 +553,32 @@ status:
 
 ##### Propagating Workspaces to Referenced Tasks
 
-Workspaces can only be propagated to `embedded` task specs, not `referenced` Tasks. 
+Workspaces can only be propagated to `embedded` task specs, not `referenced` Tasks.
 
 ```yaml
-apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1 
-kind: Task                     
+apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
+kind: Task
 metadata:
   name: workspace-propagation
 spec:
   steps:
-    - name: simple-step        
-      image: ubuntu            
-      command:                 
-        - echo                 
-      args:                    
+    - name: simple-step
+      image: ubuntu
+      command:
+        - echo
+      args:
         - $(workspaces.tr-workspace.path)
 ---
-apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1 
+apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
 kind: TaskRun
 metadata:
   generateName: propagating-workspaces-
 spec:
-  taskRef:                     
+  taskRef:
     name: workspace-propagation
-  workspaces:                  
-  - emptyDir: {}               
-    name: tr-workspace 
+  workspaces:
+  - emptyDir: {}
+    name: tr-workspace
 ```
 
 Upon execution, the above taskrun will fail because the task is referenced and workspace is not propagated. It mist be explicitly defined in the `spec` of the defined Task.
@@ -823,7 +824,7 @@ False    | TaskRunImagePullFailed | n/a
 
 When a `TaskRun` changes status, [events](events.md#taskruns) are triggered accordingly.
 
-The name of the `Pod` owned by a `TaskRun`  is univocally associated to the owning resource. 
+The name of the `Pod` owned by a `TaskRun`  is univocally associated to the owning resource.
 If a `TaskRun` resource is deleted and created with the same name, the child `Pod` will be created with the same name
 as before. The base format of the name is `<taskrun-name>-pod`. The name may vary according to the logic of
 [`kmeta.ChildName`](https://pkg.go.dev/github.com/knative/pkg/kmeta#ChildName). In case of retries of a `TaskRun`

diff --git a/pkg/reconciler/taskrun/resources/taskref_test.go b/pkg/reconciler/taskrun/resources/taskref_test.go
@@ -396,10 +396,9 @@ func TestGetTaskFunc(t *testing.T) {
 				},
 			},
 			ref: &v1beta1.TaskRef{
-				Name:       "simple",
-				APIVersion: "tekton.dev/v1beta1",
-				Kind:       v1beta1.ClusterTaskKind,
-				Bundle:     u.Host + "/remote-cluster-task",
+				Name:   "simple",
+				Kind:   v1beta1.ClusterTaskKind,
+				Bundle: u.Host + "/remote-cluster-task",
 			},
 			expected: &v1beta1.Task{
 				ObjectMeta: metav1.ObjectMeta{Name: "simple"},