Propagating object params

Prior to this, object parameters were not being propagated to the spec during resolution. After following the same logic as that for propagating parameters, we can not also propagate object params.
tektoncd · Sep 15, 2022 · a11c385 · a11c385
1 parent d1956e5
commit a11c385
Show file tree

Hide file tree

Showing 18 changed files with 1,268 additions and 124 deletions.
diff --git a/docs/pipelineruns.md b/docs/pipelineruns.md
@@ -20,6 +20,7 @@ weight: 500
         - [Scope and Precedence](#scope-and-precedence)
         - [Default Values](#default-values)
         - [Referenced Resources](#referenced-resources)
+        - [Object Parameters](#object-parameters) 
     - [Specifying custom <code>ServiceAccount</code> credentials](#specifying-custom-serviceaccount-credentials)
     - [Mapping <code>ServiceAccount</code> credentials to <code>Tasks</code>](#mapping-serviceaccount-credentials-to-tasks)
     - [Specifying a <code>Pod</code> template](#specifying-a-pod-template)
@@ -662,6 +663,136 @@ status:
   ...
 ```
 
+##### Object Parameters
+
+When using an inlined spec, object parameters from the parent `PipelineRun` will also be
+propagated to any inlined specs without needing to be explicitly defined. This
+allows authors to simplify specs by automatically propagating top-level
+parameters down to other inlined resources.
+When propagating object parameters, scope and precedence also holds as shown below.
+
+```yaml
+apiVersion: tekton.dev/v1beta1 
+kind: PipelineRun              
+metadata:
+  generateName: pipelinerun-object-param-result 
+spec:
+  params:
+    - name: gitrepo            
+      value:                   
+        url: abc.com           
+        commit: sha123         
+  pipelineSpec:                
+    tasks:                     
+      - name: task1            
+        params:                
+          - name: gitrepo      
+            value:
+              branch: main     
+              url: xyz.com     
+        taskSpec:
+          steps:
+            - name: write-result            
+              image: bash      
+              args: [          
+                "echo",        
+                "--url=$(params.gitrepo.url)",  
+                "--commit=$(params.gitrepo.commit)",
+                "--branch=$(params.gitrepo.branch)",
+              ]      
+```
+
+resolves to
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+  name: pipelinerun-object-param-resultpxp59
+  ...
+spec:
+  params:
+  - name: gitrepo
+    value:
+      commit: sha123
+      url: abc.com
+  pipelineSpec:
+    tasks:
+    - name: task1
+      params:
+      - name: gitrepo
+        value:
+          branch: main
+          url: xyz.com
+      taskSpec:
+        metadata: {}
+        spec: null
+        steps:
+        - args:
+          - echo
+          - --url=$(params.gitrepo.url)
+          - --commit=$(params.gitrepo.commit)
+          - --branch=$(params.gitrepo.branch)
+          image: bash
+          name: write-result
+          resources: {}
+status:
+  completionTime: "2022-09-08T17:22:01Z"
+  conditions:
+  - lastTransitionTime: "2022-09-08T17:22:01Z"
+    message: 'Tasks Completed: 1 (Failed: 0, Cancelled 0), Skipped: 0'
+    reason: Succeeded
+    status: "True"
+    type: Succeeded
+  pipelineSpec:
+    tasks:
+    - name: task1
+      params:
+      - name: gitrepo
+        value:
+          branch: main
+          url: xyz.com
+      taskSpec:
+        metadata: {}
+        spec: null
+        steps:
+        - args:
+          - echo
+          - --url=xyz.com
+          - --commit=sha123
+          - --branch=main
+          image: bash
+          name: write-result
+          resources: {}
+  startTime: "2022-09-08T17:21:57Z"
+  taskRuns:
+    pipelinerun-object-param-resultpxp59-task1:
+      pipelineTaskName: task1
+      status:
+        completionTime: "2022-09-08T17:22:01Z"
+        conditions:
+        - lastTransitionTime: "2022-09-08T17:22:01Z"
+          message: All Steps have completed executing
+          reason: Succeeded
+          status: "True"
+          type: Succeeded
+        podName: pipelinerun-object-param-resultpxp59-task1-pod
+        startTime: "2022-09-08T17:21:57Z"
+        steps:
+        - container: step-write-result
+          ...
+	taskSpec:
+          steps:
+          - args:
+            - echo
+            - --url=xyz.com
+            - --commit=sha123
+            - --branch=main
+            image: bash
+            name: write-result
+            resources: {}
+```
+
 ### Specifying custom `ServiceAccount` credentials
 
 You can execute the `Pipeline` in your `PipelineRun` with a specific set of credentials by

diff --git a/docs/taskruns.md b/docs/taskruns.md
@@ -15,6 +15,7 @@ weight: 300
   - [Remote Tasks](#remote-tasks)
   - [Specifying `Parameters`](#specifying-parameters)
     - [Propagated Parameters](#propagated-parameters)
+    - [Propagated Object Parameters](#propagated-object-parameters)
     - [Extra Parameters](#extra-parameters)
   - [Specifying `Resources`](#specifying-resources)
   - [Specifying `Resource` limits](#specifying-resource-limits)
@@ -266,6 +267,85 @@ status:
         echo "hello world!"
 ```
 
+#### Propagated Object Parameters
+**([alpha only](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#alpha-features))**
+
+When using an inlined `taskSpec`, object parameters from the parent `TaskRun` will be
+available to the `Task` without needing to be explicitly defined.
+
+
+**Note:** If an object parameter is being defined explicitly then you must define the spec of the object in `Properties`.
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: TaskRun
+metadata:
+  generateName: object-param-result-
+spec:
+  params:
+  - name: gitrepo
+    value:
+      commit: sha123
+      url: xyz.com
+  taskSpec:
+    steps:
+    - name: echo-object-params
+      image: bash
+      args:
+      - echo
+      - --url=$(params.gitrepo.url)
+      - --commit=$(params.gitrepo.commit)
+```
+
+On executing the task run, the object parameters will be interpolated during resolution.
+The specifications are not mutated before storage and so it remains the same.
+The status is updated.
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: TaskRun
+metadata:
+  name: object-param-result-vlnmb
+  ...
+spec:
+  params:
+  - name: gitrepo
+    value:
+      commit: sha123
+      url: xyz.com
+  serviceAccountName: default
+  taskSpec:
+    steps:
+    - args:
+      - echo
+      - --url=$(params.gitrepo.url)
+      - --commit=$(params.gitrepo.commit)
+      image: bash
+      name: echo-object-params
+      resources: {}
+status:
+  completionTime: "2022-09-08T17:09:37Z"
+  conditions:
+  - lastTransitionTime: "2022-09-08T17:09:37Z"
+    message: All Steps have completed executing
+    reason: Succeeded
+    status: "True"
+    type: Succeeded
+    ...
+  steps:
+  - container: step-echo-object-params
+    ...
+  taskSpec:
+    steps:
+    - args:
+      - echo
+      - --url=xyz.com
+      - --commit=sha123
+      image: bash
+      name: echo-object-params
+      resources: {}
+```
+
 #### Extra Parameters
 
 **([alpha only](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#alpha-features))**

diff --git a/examples/v1beta1/pipelineruns/alpha/propagated-pipeline-object-param.yaml b/examples/v1beta1/pipelineruns/alpha/propagated-pipeline-object-param.yaml
@@ -0,0 +1,28 @@
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+  generateName: pipelinerun-object-param-result
+spec:
+  params:
+    - name: gitrepo
+      value:
+        url: abc.com
+        commit: sha123
+  pipelineSpec:
+    tasks:
+      - name: task1
+        params:
+          - name: gitrepo
+            value:
+              branch: main
+              url: xyz.com
+        taskSpec:
+          steps:
+            - name: write-result
+              image: bash
+              args: [
+                "echo",
+                "--url=$(params.gitrepo.url)",
+                "--commit=$(params.gitrepo.commit)",
+                "--branch=$(params.gitrepo.branch)",
+              ]
diff --git a/examples/v1beta1/taskruns/alpha/propagated-object-parameters.yaml b/examples/v1beta1/taskruns/alpha/propagated-object-parameters.yaml
@@ -0,0 +1,19 @@
+apiVersion: tekton.dev/v1beta1
+kind: TaskRun
+metadata:
+  generateName: object-param-result-
+spec:
+  params:
+    - name: gitrepo
+      value:
+        url: "xyz.com"
+        commit: "sha123"
+  taskSpec:
+    steps:
+      - name: echo-object-params
+        image: bash
+        args: [
+          "echo",
+          "--url=$(params.gitrepo.url)",
+          "--commit=$(params.gitrepo.commit)",
+        ]
diff --git a/pkg/apis/pipeline/v1/pipeline_validation.go b/pkg/apis/pipeline/v1/pipeline_validation.go
@@ -55,8 +55,8 @@ func (ps *PipelineSpec) Validate(ctx context.Context) (errs *apis.FieldError) {
 	errs = errs.Also(validateGraph(ps.Tasks))
 	errs = errs.Also(validateParamResults(ps.Tasks))
 	// The parameter variables should be valid
-	errs = errs.Also(validatePipelineParameterVariables(ctx, ps.Tasks, ps.Params).ViaField("tasks"))
-	errs = errs.Also(validatePipelineParameterVariables(ctx, ps.Finally, ps.Params).ViaField("finally"))
+	errs = errs.Also(ValidatePipelineParameterVariables(ctx, ps.Tasks, ps.Params).ViaField("tasks"))
+	errs = errs.Also(ValidatePipelineParameterVariables(ctx, ps.Finally, ps.Params).ViaField("finally"))
 	errs = errs.Also(validatePipelineContextVariables(ps.Tasks).ViaField("tasks"))
 	errs = errs.Also(validatePipelineContextVariables(ps.Finally).ViaField("finally"))
 	errs = errs.Also(validateExecutionStatusVariables(ps.Tasks, ps.Finally))
@@ -118,10 +118,10 @@ func validatePipelineWorkspacesUsage(wss []PipelineWorkspaceDeclaration, pts []P
 	return errs
 }
 
-// validatePipelineParameterVariables validates parameters with those specified by each pipeline task,
+// ValidatePipelineParameterVariables validates parameters with those specified by each pipeline task,
 // (1) it validates the type of parameter is either string or array (2) parameter default value matches
 // with the type of that param (3) ensures that the referenced param variable is defined is part of the param declarations
-func validatePipelineParameterVariables(ctx context.Context, tasks []PipelineTask, params []ParamSpec) (errs *apis.FieldError) {
+func ValidatePipelineParameterVariables(ctx context.Context, tasks []PipelineTask, params []ParamSpec) (errs *apis.FieldError) {
 	parameterNames := sets.NewString()
 	arrayParameterNames := sets.NewString()
 	objectParameterNameKeys := map[string][]string{}
@@ -145,7 +145,10 @@ func validatePipelineParameterVariables(ctx context.Context, tasks []PipelineTas
 			}
 		}
 	}
-	return errs.Also(validatePipelineParametersVariables(tasks, "params", parameterNames, arrayParameterNames, objectParameterNameKeys))
+	if config.ValidateParameterVariablesAndWorkspaces(ctx) == true {
+		errs = errs.Also(validatePipelineParametersVariables(tasks, "params", parameterNames, arrayParameterNames, objectParameterNameKeys))
+	}
+	return errs
 }
 
 func validatePipelineParametersVariables(tasks []PipelineTask, prefix string, paramNames sets.String, arrayParamNames sets.String, objectParamNameKeys map[string][]string) (errs *apis.FieldError) {

diff --git a/pkg/apis/pipeline/v1/pipeline_validation_test.go b/pkg/apis/pipeline/v1/pipeline_validation_test.go
@@ -1132,9 +1132,10 @@ func TestValidatePipelineParameterVariables_Success(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			ctx := config.EnableAlphaAPIFields(context.Background())
-			err := validatePipelineParameterVariables(ctx, tt.tasks, tt.params)
+			ctx = config.SkipValidationDueToPropagatedParametersAndWorkspaces(ctx, false)
+			err := ValidatePipelineParameterVariables(ctx, tt.tasks, tt.params)
 			if err != nil {
-				t.Errorf("Pipeline.validatePipelineParameterVariables() returned error for valid pipeline parameters: %v", err)
+				t.Errorf("Pipeline.ValidatePipelineParameterVariables() returned error for valid pipeline parameters: %v", err)
 			}
 		})
 	}
@@ -1535,9 +1536,10 @@ func TestValidatePipelineParameterVariables_Failure(t *testing.T) {
 			if tt.api == "alpha" {
 				ctx = config.EnableAlphaAPIFields(context.Background())
 			}
-			err := validatePipelineParameterVariables(ctx, tt.tasks, tt.params)
+			ctx = config.SkipValidationDueToPropagatedParametersAndWorkspaces(ctx, false)
+			err := ValidatePipelineParameterVariables(ctx, tt.tasks, tt.params)
 			if err == nil {
-				t.Errorf("Pipeline.validatePipelineParameterVariables() did not return error for invalid pipeline parameters")
+				t.Errorf("Pipeline.ValidatePipelineParameterVariables() did not return error for invalid pipeline parameters")
 			}
 			if d := cmp.Diff(tt.expectedError.Error(), err.Error(), cmpopts.IgnoreUnexported(apis.FieldError{})); d != "" {
 				t.Errorf("PipelineSpec.Validate() errors diff %s", diff.PrintWantGot(d))