Add support for $() variable substitution in addition to ${}

In tektoncd#850 we decided that to make our syntax more similar to k8s style syntax, we will use $() for variable substitution instead of ${}. In a later iteration we may also want to make it so that anything that can be acesssed as a variable is also available as an env var to the running container, but that is TBD. In the context of this discussion we also considered removing variable substitution entirely, that conversation is continuing. We have also tried to start calling this functionality "variable substitution" instead of "templating" to make it clear that we do not intend to support more complicated templating functionality. Co-authored-by: Eli Zucker <thezuck@google.com>
afrittoli · Aug 12, 2019 · 647a7dd · 647a7dd
1 parent ddfe7da
commit 647a7dd
Show file tree

Hide file tree

Showing 34 changed files with 820 additions and 181 deletions.
diff --git a/cmd/pullrequest-init/README.md b/cmd/pullrequest-init/README.md
@@ -71,7 +71,7 @@ GitHub pull requests will output these additional files:
 
 For now, these files are *read-only*.
 
-The binary will look for GitHub credentials in the `${GITHUBTOKEN}` environment
+The binary will look for GitHub credentials in the `$GITHUBTOKEN` environment
 variable. This should generally be specified as a secret with the field name
 `githubToken` in the `PullRequestResource` definition.
 

diff --git a/docs/migrating-from-knative-build.md b/docs/migrating-from-knative-build.md
@@ -20,7 +20,8 @@ Pipeline, and provide additional flexibility and reusability.
 * BuildTemplate
   [`parameters`](https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md#parameters)
   are moved inside Task's `input.params` field, and parameter placeholder
-  strings (e.g., `${FOO}`) must be specified like `${input.parameters.FOO}`.
+  strings (e.g., `${FOO}`) must be specified like `$(input.parameters.FOO)`
+  (see [variable substitution](tasks.md#variable-substitution)).
 
 * Tasks must specify
   [`input.resources`](https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md#input-resources)
@@ -99,7 +100,7 @@ spec:
   - name: go-test  # <-- the step must specify a name.
     image: golang
     workingDir: /workspace/source  # <-- set workingdir
-    command: ['go', 'test', '${inputs.params.TARGET}']  # <-- specify inputs.params.TARGET
+    command: ['go', 'test', '$(inputs.params.TARGET)']  # <-- specify inputs.params.TARGET
 ```
 
 ### Build -> TaskRun

diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -89,9 +89,11 @@ Each declared parameter has a `type` field, assumed to be `string` if not provid
 The following example shows how `Pipeline`s can be parameterized, and these
 parameters can be passed to the `Pipeline` from a `PipelineRun`.
 
-Input parameters in the form of `${params.foo}` are replaced inside of the
+Input parameters in the form of `$(params.foo)` are replaced inside of the
 [`PipelineTask` parameters' values](#pipeline-tasks) (see also
-[templating](tasks.md#templating)).
+[variable substitution](tasks.md#variable-substitution)). _As with
+[variable substitution](tasks.md#variable-substitution)), the deprecated syntax
+`${params.foo}` will be supported until [#1170](https://github.com/tektoncd/pipeline/issues/1170)._
 
 The following `Pipeline` declares an input parameter called 'context', and uses
 it in the `PipelineTask`'s parameter. The `description` and `default` fields for
@@ -118,7 +120,7 @@ spec:
         - name: pathToDockerFile
           value: Dockerfile
         - name: pathToContext
-          value: "${params.context}"
+          value: "$(params.context)"
 ```
 
 The following `PipelineRun` supplies a value for `context`:

diff --git a/docs/resources.md b/docs/resources.md
@@ -431,7 +431,7 @@ spec:
       secretName: target-cluster-secrets
 ```
 
-Example usage of the cluster resource in a Task:
+Example usage of the cluster resource in a Task, using [variable substitution](tasks.md#variable-substitution):
 
 ```yaml
 apiVersion: tekton.dev/v1alpha1
@@ -455,8 +455,8 @@ spec:
       args:
         - "-c"
         - kubectl --kubeconfig
-          /workspace/${inputs.resources.testCluster.Name}/kubeconfig --context
-          ${inputs.resources.testCluster.Name} apply -f /workspace/service.yaml'
+          /workspace/$(inputs.resources.testCluster.Name)/kubeconfig --context
+          $(inputs.resources.testCluster.Name) apply -f /workspace/service.yaml'
 ```
 
 ### Storage Resource

diff --git a/docs/tasks.md b/docs/tasks.md
@@ -24,7 +24,7 @@ entire Kubernetes cluster.
   - [Volumes](#volumes)
   - [Container Template **deprecated**](#step-template)
   - [Step Template](#step-template)
-  - [Templating](#templating)
+  - [Variable Substitution](#variable-substitution)
 - [Examples](#examples)
 
 ## ClusterTask
@@ -172,7 +172,7 @@ The following example shows how Tasks can be parameterized, and these parameters
 can be passed to the `Task` from a `TaskRun`.
 
 Input parameters in the form of `${inputs.params.foo}` are replaced inside of
-the [`steps`](#steps) (see also [templating](#templating)).
+the [`steps`](#steps) (see also [variable substitution](#variable-substitution)).
 
 The following `Task` declares an input parameter called 'flags', and uses it in
 the `steps.args` list.
@@ -227,7 +227,7 @@ Input resources, like source code (git) or artifacts, are dumped at path
 [volume](https://kubernetes.io/docs/concepts/storage/volumes/) and is available
 to all [`steps`](#steps) of your `Task`. The path that the resources are mounted
 at can be overridden with the `targetPath` value. Steps can use the `path`
-[template](#Templating) key to refer to the local path to the mounted resource.
+[variable substitution](#variable-substitution) key to refer to the local path to the mounted resource.
 
 ### Outputs
 
@@ -346,7 +346,7 @@ For example, use volumes to accomplish one of the following common tasks:
 Specifies a [`Container`](https://kubernetes.io/docs/concepts/containers/)
 configuration that will be used as the basis for all [`steps`](#steps) in your
 `Task`. Configuration in an individual step will override or merge with the
-container template's configuration.
+step template's configuration.
 
 In the example below, the `Task` specifies a `stepTemplate` with the
 environment variable `FOO` set to `bar`. The first step will use that value for
@@ -369,39 +369,43 @@ steps:
         value: "baz"
 ```
 
-### Templating
 
-`Tasks` support templating using values from all [`inputs`](#inputs) and
+### Variable Subtituation
+
+`Tasks` support string replacement using values from all [`inputs`](#inputs) and
 [`outputs`](#outputs).
 
 [`PipelineResources`](resources.md) can be referenced in a `Task` spec like
 this, where `<name>` is the Resource Name and `<key>` is a one of the resource's
 `params`:
 
 ```shell
-${inputs.resources.<name>.<key>}
+$(inputs.resources.<name>.<key>)
 ```
 
 Or for an output resource:
 
 ```shell
-${outputs.resources.<name>.<key>}
+$(outputs.resources.<name>.<key>)
 ```
 
 The local path to a resource on the mounted volume can be accessed using the
 `path` key:
 
 ```shell
-${inputs.resouces.<name>.path}
+$(inputs.resouces.<name>.path)
 ```
 
 To access an input parameter, replace `resources` with `params`.
 
 ```shell
-${inputs.params.<name>}
+$(inputs.params.<name>)
 ```
 
-#### Templating Parameters of Type `Array`
+_The deprecated syntax `${}`, e.g. `${inputs.params.<name>}` will be supported
+until [#1170](https://github.com/tektoncd/pipeline/issues/1170)._
+
+#### Variable Substitution with Parameters of Type `Array`
 
 Referenced parameters of type `array` will expand to insert the array elements in the reference string's spot.
 
@@ -423,28 +427,28 @@ Note that array parameters __*must*__ be referenced in a completely isolated str
 Any other attempt to reference an array is invalid and will throw an error. 
 
 For instance, if `build-args` is a declared parameter of type `array`, then this is an invalid step because 
-the template string isn't isolated:
+the string isn't isolated:
 ```
  - name: build-step
       image: gcr.io/cloud-builders/some-image
-      args: ["build", "additionalArg ${inputs.params.build-args}"]
+      args: ["build", "additionalArg $(inputs.params.build-args)"]
 ```
 
 Similarly, referencing `build-args` in a non-array field is also invalid:
 ```
  - name: build-step
-      image: "${inputs.params.build-args}"
+      image: "$(inputs.params.build-args)"
       args: ["build", "args"]
 ```
 
 A valid reference to the `build-args` parameter is isolated and in an eligible field (`args`, in this case):
 ```
  - name: build-step
       image: gcr.io/cloud-builders/some-image
-      args: ["build", "${inputs.params.build-args}", "additonalArg"]
+      args: ["build", "$(inputs.params.build-args)", "additonalArg"]
 ```
 
-#### Templating Volumes
+#### Variable Substitution within Volumes
 
 Task volume names and different
 [types of volumes](https://kubernetes.io/docs/concepts/storage/volumes/#types-of-volumes)
@@ -521,7 +525,7 @@ spec:
         - name: docker-socket
           mountPath: /var/run/docker.sock
 
-  # As an implementation detail, this template mounts the host's daemon socket.
+  # As an implementation detail, this Task mounts the host's daemon socket.
   volumes:
     - name: docker-socket
       hostPath:

diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -152,7 +152,7 @@ spec:
 
 The following is a `Task` with inputs and outputs. The input resource is a
 GitHub repository and the output is the image produced from that source. The
-args of the task command support templating so that the definition of task is
+args of the task command support variable substitution so that the definition of task is
 constant and the value of parameters can change in runtime.
 
 ```yaml
@@ -190,13 +190,13 @@ spec:
       command:
         - /kaniko/executor
       args:
-        - --dockerfile=${inputs.params.pathToDockerFile}
-        - --destination=${outputs.resources.builtImage.url}
-        - --context=${inputs.params.pathToContext}
+        - --dockerfile=$(inputs.params.pathToDockerFile}
+        - --destination=$(outputs.resources.builtImage.url}
+        - --context=$(inputs.params.pathToContext}
 ```
 
 `TaskRun` binds the inputs and outputs to already defined `PipelineResources`,
-sets values to the parameters used for templating in addition to executing the
+sets values to the parameters used for variable substitution in addition to executing the
 task steps.
 
 ```yaml
@@ -325,7 +325,7 @@ A [`Pipeline`](pipelines.md) defines a list of tasks to execute in order, while
 also indicating if any outputs should be used as inputs of a following task by
 using [the `from` field](pipelines.md#from) and also indicating
 [the order of executing (using the `runAfter` and `from` fields)](pipelines.md#ordering).
-The same templating you used in tasks is also available in pipeline.
+The same variable substitution you used in tasks is also available in pipeline.
 
 For example:
 
@@ -411,10 +411,10 @@ spec:
       args:
         - "w"
         - "-i"
-        - "${inputs.params.yqArg}"
-        - "${inputs.params.path}"
-        - "${inputs.params.yamlPathToImage}"
-        - "${inputs.resources.image.url}"
+        - "$(inputs.params.yqArg)"
+        - "$(inputs.params.path)"
+        - "$(inputs.params.yamlPathToImage)"
+        - "$(inputs.resources.image.url)"
     - name: run-kubectl
       image: lachlanevenson/k8s-kubectl
       command: ["kubectl"]

diff --git a/examples/README.md b/examples/README.md
@@ -10,7 +10,7 @@ In few examples to demonstrate tasks that push image to registry, sample URL
 will need to change the values of this sample registry URL to a registry you can
 push to from inside your cluster. If you are following instructions
 [here](../DEVELOPMENT.md#getting-started) to setup then use the value of
-`${KO_DOCKER_REPO}` instead of `gcr.io/christiewilson-catfactory`.
+`$KO_DOCKER_REPO` instead of `gcr.io/christiewilson-catfactory`.
 
 ```bash
 # To invoke the build-push Task only

diff --git a/examples/pipelineruns/output-pipelinerun.yaml b/examples/pipelineruns/output-pipelinerun.yaml
@@ -53,7 +53,7 @@ spec:
   - name: read
     image: ubuntu
     command: ["/bin/bash"]
-    args: ['${inputs.params.args}'] # tests that new targetpath and previous task output is dumped
+    args: ['$(inputs.params.args)'] # tests that new targetpath and previous task output is dumped
 ---
 #The Output of the first Task (git resource) create-file is given as an `Input`
 # to the next `Task` check-stuff-file-exists using`from` clause.

diff --git a/examples/pipelineruns/pipelinerun.yaml b/examples/pipelineruns/pipelinerun.yaml
@@ -100,9 +100,9 @@ spec:
     command:
     - /kaniko/executor
     args:
-    - --dockerfile=${inputs.params.pathToDockerFile}
-    - --destination=${outputs.resources.builtImage.url}
-    - --context=${inputs.params.pathToContext}
+    - --dockerfile=$(inputs.params.pathToDockerFile)
+    - --destination=$(outputs.resources.builtImage.url)
+    - --context=$(inputs.params.pathToContext)
 ---
 #This task deploys with kubectl apply -f <filename>
 apiVersion: tekton.dev/v1alpha1
@@ -130,17 +130,17 @@ spec:
     args:
     - "w"
     - "-i"
-    - "${inputs.params.yqArg}"
-    - "${inputs.params.path}"
-    - "${inputs.params.yamlPathToImage}"
-    - "${inputs.resources.image.url}"
+    - "$(inputs.params.yqArg)"
+    - "$(inputs.params.path)"
+    - "$(inputs.params.yamlPathToImage)"
+    - "$(inputs.resources.image.url)"
   - name: run-kubectl
     image: lachlanevenson/k8s-kubectl
     command: ['kubectl']
     args:
     - 'apply'
     - '-f'
-    - '${inputs.params.path}'
+    - '$(inputs.params.path)'
 ---
 # This Pipeline Builds two microservice images(https://github.com/GoogleContainerTools/skaffold/tree/master/examples/microservices)
 # from the Skaffold repo (https://github.com/GoogleContainerTools/skaffold) and deploys them to the repo currently running Tekton Pipelines.

diff --git a/examples/taskruns/task-env.yaml b/examples/taskruns/task-env.yaml
@@ -16,41 +16,41 @@ spec:
       - name: BAR
         description: BAR variable
       - name: FOOBAR
-        description: FOODBAR variable
+        description: FOOBAR variable
         default: foobar
   steps:
     # Test the environment variables are set in the task
     - name: foo
       image: ubuntu
       command: ["bash"]
-      args: ["-c", '[[ ${FOO} == "foo" ]]']
+      args: ["-c", '[[ $(FOO) == "foo" ]]']
       env:
         - name: FOO
-          value: ${inputs.params.FOO}
+          value: $(inputs.params.FOO)
     - name: foobar
       image: ubuntu
       command: ["bash"]
-      args: ["-c", '[[ ${FOOBAR} == "foobar" ]]']
+      args: ["-c", '[[ $(FOOBAR) == "foobar" ]]']
       env:
         - name: FOOBAR
-          value: ${inputs.params.FOOBAR}
+          value: $(inputs.params.FOOBAR)
     - name: bar
       image: ubuntu
       command: ["bash"]
-      args: ["-c", '[[ ${BAR} == "bar" ]]']
+      args: ["-c", '[[ $(BAR) == "bar" ]]']
       env:
         - name: BAR
-          value: ${inputs.params.BAR}
+          value: $(inputs.params.BAR)
     # Use the env var from the stepTemplate
     - name: qux-no-override
       image: ubuntu
       command: ["bash"]
-      args: ["-c", '[[ ${QUX} == "original" ]]']
+      args: ["-c", '[[ $(QUX) == "original" ]]']
     # Override the env var in the stepTemplate
     - name: qux-override
       image: ubuntu
       command: ["bash"]
-      args: ["-c", '[[ ${QUX} == "override" ]]']
+      args: ["-c", '[[ $(QUX) == "override" ]]']
       env:
         - name: QUX
           value: override

diff --git a/examples/taskruns/task-multiple-output-image.yaml b/examples/taskruns/task-multiple-output-image.yaml
@@ -6,7 +6,7 @@ spec:
   type: image
   params:
   - name: url
-    value: gcr.io/christiewilson-catfactory/leeroy-web # Replace this URL with ${KO_DOCKER_REPO}
+    value: gcr.io/christiewilson-catfactory/leeroy-web # Replace this URL with $KO_DOCKER_REPO
 ---
 apiVersion: tekton.dev/v1alpha1
 kind: PipelineResource
@@ -16,7 +16,7 @@ spec:
   type: image
   params:
   - name: url
-    value: gcr.io/christiewilson-catfactory/leeroy-web # Replace this URL with ${KO_DOCKER_REPO}
+    value: gcr.io/christiewilson-catfactory/leeroy-web # Replace this URL with $KO_DOCKER_REPO
 ---
 # This demo modifies the cluster (deploys to it) you must use a service
 # account with permission to admin the cluster (or make your default user an admin