Add structural OpenAPI schema to Tekton CRDs

config/300-crds/300-verificationpolicy.yaml

@@ -24,25 +24,117 @@ 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:
+          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

docs/pipeline-api.md

@@ -766,7 +766,8 @@ PipelineSpec
 <td>
 <em>(Optional)</em>
 <p>Specifying PipelineSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<code>disable-inline-spec</code> feature flag.
+See Pipeline.spec (API version: tekton.dev/v1)</p>
 </td>
 </tr>
 <tr>
@@ -1004,7 +1005,8 @@ source mounted into /workspace.</p>
 </td>
 <td>
 <p>Volumes is a collection of volumes that are available to mount into the
-steps of the build.</p>
+steps of the build.
+See Pod.spec.volumes (API version: v1)</p>
 </td>
 </tr>
 <tr>
@@ -1189,8 +1191,9 @@ TaskSpec
 </td>
 <td>
 <em>(Optional)</em>
-<p>Specifying PipelineSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<p>Specifying TaskSpec can be disabled by setting
+<code>disable-inline-spec</code> feature flag.
+See Task.spec (API version: tekton.dev/v1)</p>
 </td>
 </tr>
 <tr>
@@ -2401,7 +2404,8 @@ PipelineSpec
 <td>
 <em>(Optional)</em>
 <p>Specifying PipelineSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<code>disable-inline-spec</code> feature flag.
+See Pipeline.spec (API version: tekton.dev/v1)</p>
 </td>
 </tr>
 <tr>
@@ -2618,7 +2622,8 @@ PipelineSpec
 </em>
 </td>
 <td>
-<p>PipelineRunSpec contains the exact spec used to instantiate the run</p>
+<p>PipelineSpec contains the exact spec used to instantiate the run.
+See Pipeline.spec (API version: tekton.dev/v1)</p>
 </td>
 </tr>
 <tr>
@@ -2942,7 +2947,8 @@ EmbeddedTask
 <em>(Optional)</em>
 <p>TaskSpec is a specification of a task
 Specifying TaskSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<code>disable-inline-spec</code> feature flag.
+See Task.spec (API version: tekton.dev/v1)</p>
 </td>
 </tr>
 <tr>
@@ -3071,7 +3077,8 @@ PipelineSpec
 <p>PipelineSpec is a specification of a pipeline
 Note: PipelineSpec is in preview mode and not yet supported
 Specifying PipelineSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<code>disable-inline-spec</code> feature flag.
+See Pipeline.spec (API version: tekton.dev/v1)</p>
 </td>
 </tr>
 <tr>
@@ -5641,8 +5648,9 @@ TaskSpec
 </td>
 <td>
 <em>(Optional)</em>
-<p>Specifying PipelineSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<p>Specifying TaskSpec can be disabled by setting
+<code>disable-inline-spec</code> feature flag.
+See Task.spec (API version: tekton.dev/v1)</p>
 </td>
 </tr>
 <tr>
@@ -6148,7 +6156,8 @@ source mounted into /workspace.</p>
 </td>
 <td>
 <p>Volumes is a collection of volumes that are available to mount into the
-steps of the build.</p>
+steps of the build.
+See Pod.spec.volumes (API version: v1)</p>
 </td>
 </tr>
 <tr>
@@ -6392,7 +6401,8 @@ Kubernetes core/v1.PersistentVolumeClaim
 <td>
 <em>(Optional)</em>
 <p>VolumeClaimTemplate is a template for a claim that will be created in the same namespace.
-The PipelineRun controller is responsible for creating a unique claim for each instance of PipelineRun.</p>
+The PipelineRun controller is responsible for creating a unique claim for each instance of PipelineRun.
+See PersistentVolumeClaim (API version: v1)</p>
 </td>
 </tr>
 <tr>
@@ -8631,7 +8641,8 @@ source mounted into /workspace.</p>
 </td>
 <td>
 <p>Volumes is a collection of volumes that are available to mount into the
-steps of the build.</p>
+steps of the build.
+See Pod.spec.volumes (API version: v1)</p>
 </td>
 </tr>
 <tr>
@@ -9156,7 +9167,8 @@ PipelineSpec
 <td>
 <em>(Optional)</em>
 <p>Specifying PipelineSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<code>disable-inline-spec</code> feature flag.
+See Pipeline.spec (API version: tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>
@@ -9689,7 +9701,8 @@ source mounted into /workspace.</p>
 </td>
 <td>
 <p>Volumes is a collection of volumes that are available to mount into the
-steps of the build.</p>
+steps of the build.
+See Pod.spec.volumes (API version: v1)</p>
 </td>
 </tr>
 <tr>
@@ -9889,8 +9902,9 @@ TaskSpec
 </td>
 <td>
 <em>(Optional)</em>
-<p>Specifying PipelineSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<p>Specifying TaskSpec can be disabled by setting
+<code>disable-inline-spec</code> feature flag.
+See Task.spec (API version: tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>
@@ -11578,7 +11592,8 @@ PipelineSpec
 <td>
 <em>(Optional)</em>
 <p>Specifying PipelineSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<code>disable-inline-spec</code> feature flag.
+See Pipeline.spec (API version: tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>
@@ -11872,7 +11887,8 @@ PipelineSpec
 </em>
 </td>
 <td>
-<p>PipelineRunSpec contains the exact spec used to instantiate the run</p>
+<p>PipelineSpec contains the exact spec used to instantiate the run.
+See Pipeline.spec (API version: tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>
@@ -12212,7 +12228,8 @@ EmbeddedTask
 <em>(Optional)</em>
 <p>TaskSpec is a specification of a task
 Specifying TaskSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<code>disable-inline-spec</code> feature flag.
+See Task.spec (API version: tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>
@@ -12354,8 +12371,9 @@ PipelineSpec
 <em>(Optional)</em>
 <p>PipelineSpec is a specification of a pipeline
 Note: PipelineSpec is in preview mode and not yet supported
-Specifying TaskSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+Specifying PipelineSpec can be disabled by setting
+<code>disable-inline-spec</code> feature flag.
+See Pipeline.spec (API version: tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>
@@ -15627,8 +15645,9 @@ TaskSpec
 </td>
 <td>
 <em>(Optional)</em>
-<p>Specifying PipelineSpec can be disabled by setting
-<code>disable-inline-spec</code> feature flag..</p>
+<p>Specifying TaskSpec can be disabled by setting
+<code>disable-inline-spec</code> feature flag.
+See Task.spec (API version: tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>
@@ -15924,7 +15943,8 @@ CloudEventResource.</p>
 <td>
 <em>(Optional)</em>
 <p>RetriesStatus contains the history of TaskRunStatus in case of a retry in order to keep record of failures.
-All TaskRunStatus stored in RetriesStatus will have no date within the RetriesStatus as is redundant.</p>
+All TaskRunStatus stored in RetriesStatus will have no date within the RetriesStatus as is redundant.
+See TaskRun.status (API version: tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>
@@ -15979,7 +15999,8 @@ TaskSpec
 </em>
 </td>
 <td>
-<p>TaskSpec contains the Spec from the dereferenced Task definition used to instantiate this TaskRun.</p>
+<p>TaskSpec contains the Spec from the dereferenced Task definition used to instantiate this TaskRun.
+See Task.spec (API version tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>
@@ -16151,7 +16172,8 @@ source mounted into /workspace.</p>
 </td>
 <td>
 <p>Volumes is a collection of volumes that are available to mount into the
-steps of the build.</p>
+steps of the build.
+See Pod.spec.volumes (API version: v1)</p>
 </td>
 </tr>
 <tr>
@@ -16395,7 +16417,8 @@ Kubernetes core/v1.PersistentVolumeClaim
 <td>
 <em>(Optional)</em>
 <p>VolumeClaimTemplate is a template for a claim that will be created in the same namespace.
-The PipelineRun controller is responsible for creating a unique claim for each instance of PipelineRun.</p>
+The PipelineRun controller is responsible for creating a unique claim for each instance of PipelineRun.
+See PersistentVolumeClaim (API version: v1)</p>
 </td>
 </tr>
 <tr>
@@ -16822,7 +16845,8 @@ tasks in a pipeline.</p>
 </td>
 <td>
 <em>(Optional)</em>
-<p>RetriesStatus contains the history of CustomRunStatus, in case of a retry.</p>
+<p>RetriesStatus contains the history of CustomRunStatus, in case of a retry.
+See CustomRun.status (API version: tekton.dev/v1beta1)</p>
 </td>
 </tr>
 <tr>

examples/v1/pipelineruns/alpha/stepaction-params.yaml

@@ -50,7 +50,7 @@ spec:
     - name: objectparam
       value:
         key2: "pipelinerun key2"
-  PipelineSpec:
+  pipelineSpec:
     tasks:
       - name: run-action
         taskSpec: