Add structural OpenAPI schema to Tekton CRDs

- Implement POSIX script to update the OpenAPI schema to Tekton CRDs using controller-gen
- Add updated CRDs with OpenAPI schema

Note1: the current script 'hack/update-schemas.sh' return several errors/warnings and status code 1 from execution of the controller-gen CLI due to issues when parsing the schema from the source code.

Note2: the controller-gen does not preserve the field "x-kubernetes-preserve-unknown-fields: true" in the root of the schema. This field is added by the 'hack/update-schemas.sh' script

Note3: Markes were addded to avoid creating the schema for recursive types that results in invalid schemata. Related issue: kubernetes-sigs/controller-tools#585

Note4: Schema for PipelineSpec was omitted from PipelineRun to reduce size. A comment was added in the description of the field for the user to refer to the schema of Pipeline.

Note5: Schema of TaskSpec was omitted from TaskRun to reduce size. A comment was added in the description of the field for the user to refer to the schema of Task.

config/300-crds/300-verificationpolicy.yaml

@@ -24,25 +24,125 @@ metadata:
 spec:
   group: tekton.dev
   versions:
-  - name: v1alpha1
-    served: true
-    storage: true
-    schema:
-      openAPIV3Schema:
-        type: object
-        # One can use x-kubernetes-preserve-unknown-fields: true
-        # at the root of the schema (and inside any properties, additionalProperties)
-        # to get the traditional CRD behaviour that nothing is pruned, despite
-        # setting spec.preserveUnknownProperties: false.
-        #
-        # See https://kubernetes.io/blog/2019/06/20/crd-structural-schema/
-        # See issue: https://github.com/knative/serving/issues/912
-        x-kubernetes-preserve-unknown-fields: true
+    - name: v1alpha1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          # One can use x-kubernetes-preserve-unknown-fields: true
+          # at the root of the schema (and inside any properties, additionalProperties)
+          # to get the traditional CRD behaviour that nothing is pruned, despite
+          # setting spec.preserveUnknownProperties: false.
+          #
+          # See https://kubernetes.io/blog/2019/06/20/crd-structural-schema/
+          # See issue: https://github.com/knative/serving/issues/912
+          x-kubernetes-preserve-unknown-fields: true
+          description: |-
+            VerificationPolicy defines the rules to verify Tekton resources.
+            VerificationPolicy can config the mapping from resources to a list of public
+            keys, so when verifying the resources we can use the corresponding public keys.
+          type: object
+          required:
+            - spec
+          properties:
+            apiVersion:
+              description: |-
+                APIVersion defines the versioned schema of this representation of an object.
+                Servers should convert recognized schemas to the latest internal value, and
+                may reject unrecognized values.
+                More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
+              type: string
+            kind:
+              description: |-
+                Kind is a string value representing the REST resource this object represents.
+                Servers may infer this from the endpoint the client submits requests to.
+                Cannot be updated.
+                In CamelCase.
+                More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+              type: string
+            metadata:
+              type: object
+            spec:
+              description: Spec holds the desired state of the VerificationPolicy.
+              type: object
+              required:
+                - authorities
+                - resources
+              properties:
+                authorities:
+                  description: Authorities defines the rules for validating signatures.
+                  type: array
+                  items:
+                    description: The Authority block defines the keys for validating signatures.
+                    type: object
+                    required:
+                      - name
+                    properties:
+                      key:
+                        description: Key contains the public key to validate the resource.
+                        type: object
+                        properties:
+                          data:
+                            description: Data contains the inline public key.
+                            type: string
+                          hashAlgorithm:
+                            description: HashAlgorithm always defaults to sha256 if the algorithm hasn't been explicitly set
+                            type: string
+                          kms:
+                            description: |-
+                              KMS contains the KMS url of the public key
+                              Supported formats differ based on the KMS system used.
+                              One example of a KMS url could be:
+                              gcpkms://projects/[PROJECT]/locations/[LOCATION]>/keyRings/[KEYRING]/cryptoKeys/[KEY]/cryptoKeyVersions/[KEY_VERSION]
+                              For more examples please refer https://docs.sigstore.dev/cosign/kms_support.
+                              Note that the KMS is not supported yet.
+                            type: string
+                          secretRef:
+                            description: SecretRef sets a reference to a secret with the key.
+                            type: object
+                            properties:
+                              name:
+                                description: name is unique within a namespace to reference a secret resource.
+                                type: string
+                              namespace:
+                                description: namespace defines the space within which the secret name must be unique.
+                                type: string
+                            x-kubernetes-map-type: atomic
+                      name:
+                        description: Name is the name for this authority.
+                        type: string
+                mode:
+                  description: |-
+                    Mode controls whether a failing policy will fail the taskrun/pipelinerun, or only log the warnings
+                    enforce - fail the taskrun/pipelinerun if verification fails (default)
+                    warn - don't fail the taskrun/pipelinerun if verification fails but log warnings
+                  type: string
+                resources:
+                  description: |-
+                    Resources defines the patterns of resources sources that should be subject to this policy.
+                    For example, we may want to apply this Policy from a certain GitHub repo.
+                    Then the ResourcesPattern should be valid regex. E.g. If using gitresolver, and we want to config keys from a certain git repo.
+                    `ResourcesPattern` can be `https://github.com/tektoncd/catalog.git`, we will use regex to filter out those resources.
+                  type: array
+                  items:
+                    description: ResourcePattern defines the pattern of the resource source
+                    type: object
+                    required:
+                      - pattern
+                    properties:
+                      pattern:
+                        description: |-
+                          Pattern defines a resource pattern. Regex is created to filter resources based on `Pattern`
+                          Example patterns:
+                          GitHub resource: https://github.com/tektoncd/catalog.git, https://github.com/tektoncd/*
+                          Bundle resource: gcr.io/tekton-releases/catalog/upstream/git-clone, gcr.io/tekton-releases/catalog/upstream/*
+                          Hub resource: https://artifacthub.io/*,
+                        type: string
   names:
     kind: VerificationPolicy
     plural: verificationpolicies
     singular: verificationpolicy
     categories:
-    - tekton
-    - tekton-pipelines
+      - tekton
+      - tekton-pipelines
   scope: Namespaced

hack/update-codegen.sh

@@ -109,3 +109,6 @@ ${REPO_ROOT_DIR}/hack/update-openapigen.sh
 
 # Make sure the generated API reference docs are up-to-date
 ${REPO_ROOT_DIR}/hack/update-reference-docs.sh
+
+# Add structural OpenAPI schema to Tekton CRDs
+${REPO_ROOT_DIR}/hack/update-schemas.sh

hack/update-schemas.sh

@@ -0,0 +1,50 @@
+#!/bin/sh
+
+CRD_PATH=./config/300-crds
+
+for FILENAME in `find $CRD_PATH -type f`;
+do
+    echo "Processing file $FILENAME"
+
+    # NOTE: APIs for the group tekton.dev are implemented under ./pkg/apis/pipeline,
+    # while the ResolutionRequest from group resolution.tekton.dev is implemented under ./pkg/apis/resolution
+
+    GROUP=$(grep -E '^  group:' $FILENAME)
+    GROUP=${GROUP#"  group: "}
+    if [ "$GROUP" = "tekton.dev" ]; then
+      API_SUBDIR='pipeline'
+    else
+      API_SUBDIR=${GROUP%".tekton.dev"}
+    fi
+    echo "GROUP: $GROUP"
+    echo "API_SUBDIR: $API_SUBDIR"
+
+    TEMP_DIR=$(mktemp -d)
+    cp -p $FILENAME $TEMP_DIR/.
+    go run sigs.k8s.io/controller-tools/cmd/[email protected] \
+      schemapatch:manifests=$TEMP_DIR,generateEmbeddedObjectMeta=false \
+      output:dir=$CRD_PATH \
+      paths=./pkg/apis/$API_SUBDIR/...
+
+    # NOTE: the controller-gen removes the field 'x-kubernetes-preserve-unknown-fields: true'
+    # The command below restores the field.
+    cat >$TEMP_DIR/tmp-fix <<EOF
+# One can use x-kubernetes-preserve-unknown-fields: true
+# at the root of the schema (and inside any properties, additionalProperties)
+# to get the traditional CRD behaviour that nothing is pruned, despite
+# setting spec.preserveUnknownProperties: false.
+#
+# See https://kubernetes.io/blog/2019/06/20/crd-structural-schema/
+# See issue: https://github.com/knative/serving/issues/912
+x-kubernetes-preserve-unknown-fields: true
+EOF
+    FIELD_IDENTATION="$(grep 'openAPIV3Schema:' $FILENAME | head -1)"
+    FIELD_IDENTATION="${FIELD_IDENTATION%openAPIV3Schema:}  "
+    sed -i "s/^/$FIELD_IDENTATION/" $TEMP_DIR/tmp-fix
+
+    if ! grep -qF "$(head -n1 $TEMP_DIR/tmp-fix)" $FILENAME; then
+        sed -i "/        openAPIV3Schema:/r $TEMP_DIR/tmp-fix" $FILENAME
+    fi
+
+    rm -rf $TEMP_DIR
+done

pkg/apis/pipeline/v1/pipeline_types.go

@@ -248,6 +248,8 @@ type PipelineTask struct {
 	// Specifying PipelineSpec can be disabled by setting
 	// `disable-inline-spec` feature flag..
 	// +optional
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Schemaless
 	PipelineSpec *PipelineSpec `json:"pipelineSpec,omitempty"`
 
 	// OnError defines the exiting behavior of a PipelineRun on error

pkg/apis/pipeline/v1/pipelinerun_types.go

@@ -250,8 +250,11 @@ type PipelineRunSpec struct {
 	// +optional
 	PipelineRef *PipelineRef `json:"pipelineRef,omitempty"`
 	// Specifying PipelineSpec can be disabled by setting
-	// `disable-inline-spec` feature flag..
+	// `disable-inline-spec` feature flag.
+	// Please, refer to the schema of Pipeline for details.
 	// +optional
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Schemaless
 	PipelineSpec *PipelineSpec `json:"pipelineSpec,omitempty"`
 	// Params is a list of parameter names and values.
 	// +listType=atomic

pkg/apis/pipeline/v1/taskrun_types.go

@@ -44,9 +44,12 @@ type TaskRunSpec struct {
 	// no more than one of the TaskRef and TaskSpec may be specified.
 	// +optional
 	TaskRef *TaskRef `json:"taskRef,omitempty"`
-	// Specifying PipelineSpec can be disabled by setting
-	// `disable-inline-spec` feature flag..
+	// Specifying TaskSpec can be disabled by setting
+	// `disable-inline-spec` feature flag.
+	// Please, refer to the schema of Task for details.
 	// +optional
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Schemaless
 	TaskSpec *TaskSpec `json:"taskSpec,omitempty"`
 	// Used for cancelling a TaskRun (and maybe more later on)
 	// +optional
@@ -290,6 +293,8 @@ type TaskRunStatusFields struct {
 	// All TaskRunStatus stored in RetriesStatus will have no date within the RetriesStatus as is redundant.
 	// +optional
 	// +listType=atomic
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Schemaless
 	RetriesStatus []TaskRunStatus `json:"retriesStatus,omitempty"`
 
 	// Results are the list of results written out by the task's containers

pkg/apis/pipeline/v1beta1/pipeline_types.go

@@ -262,6 +262,8 @@ type PipelineTask struct {
 	// Specifying TaskSpec can be disabled by setting
 	// `disable-inline-spec` feature flag..
 	// +optional
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Schemaless
 	PipelineSpec *PipelineSpec `json:"pipelineSpec,omitempty"`
 
 	// OnError defines the exiting behavior of a PipelineRun on error

pkg/apis/pipeline/v1beta1/pipelinerun_types.go

@@ -253,8 +253,11 @@ type PipelineRunSpec struct {
 	// +optional
 	PipelineRef *PipelineRef `json:"pipelineRef,omitempty"`
 	// Specifying PipelineSpec can be disabled by setting
-	// `disable-inline-spec` feature flag..
+	// `disable-inline-spec` feature flag.
+	// Please, refer to the schema of Pipeline for details.
 	// +optional
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Schemaless
 	PipelineSpec *PipelineSpec `json:"pipelineSpec,omitempty"`
 	// Resources is a list of bindings specifying which actual instances of
 	// PipelineResources to use for the resources the Pipeline has declared

pkg/apis/pipeline/v1beta1/taskrun_types.go

@@ -49,9 +49,12 @@ type TaskRunSpec struct {
 	// no more than one of the TaskRef and TaskSpec may be specified.
 	// +optional
 	TaskRef *TaskRef `json:"taskRef,omitempty"`
-	// Specifying PipelineSpec can be disabled by setting
-	// `disable-inline-spec` feature flag..
+	// Specifying TaskSpec can be disabled by setting
+	// `disable-inline-spec` feature flag.
+	// Please, refer to the schema of Task for details.
 	// +optional
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Schemaless
 	TaskSpec *TaskSpec `json:"taskSpec,omitempty"`
 	// Used for cancelling a TaskRun (and maybe more later on)
 	// +optional
@@ -296,6 +299,8 @@ type TaskRunStatusFields struct {
 	// All TaskRunStatus stored in RetriesStatus will have no date within the RetriesStatus as is redundant.
 	// +optional
 	// +listType=atomic
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Schemaless
 	RetriesStatus []TaskRunStatus `json:"retriesStatus,omitempty"`
 
 	// Results from Resources built during the TaskRun.

pkg/apis/run/v1beta1/customrunstatus_types.go

@@ -60,6 +60,8 @@ type CustomRunStatusFields struct {
 
 	// RetriesStatus contains the history of CustomRunStatus, in case of a retry.
 	// +optional
+	// +kubebuilder:pruning:PreserveUnknownFields
+	// +kubebuilder:validation:Schemaless
 	RetriesStatus []CustomRunStatus `json:"retriesStatus,omitempty"`
 
 	// ExtraFields holds arbitrary fields provided by the custom task