Merge pull request #140 from SaschaSchwarze0/sascha-docs-v0.14.0

Sync documentation from shipwright-io/build at v0.14.0 level

Author: openshift-merge-bot[bot]

content/en/blog/posts/2024-11-15-release-v0.14.0.md

@@ -15,18 +15,18 @@ In this release, we have put together some nice features:
 
 Keeping your environments secure is key these days. For container images, scanning them is widely adopted. Shipwright now performs a shift left of those scans by incorporating image scanning into the image build itself. We'll ensure that a vulnerable image never makes it into your container registry (though, you'd still have to re-scan it regularly to determine when it becomes vulnerable). This is a great safeguard for example against base images you consume in your Dockerfile that suddenly are not updated anymore.
 
-You can read more about it in the separate blog post [Building Secure Container images with Shipwright](2024-07-15-vulnerability-scanning.md).
+You can read more about it in the separate blog post [Building Secure Container images with Shipwright](../../../07/15/building-secure-container-images-with-shipwright).
 
 ### Parameters in the CLI
 
-The Shipwright CLI finally received the first support for [build parameters](../../docs/build/build.md#defining-paramvalues). You can use the `--param-value` argument to provide values for strategy parameters such as the Go version and Go flags in our [ko sample build strategy](https://github.com/shipwright-io/build/blob/v0.14.0/samples/v1beta1/buildstrategy/ko/buildstrategy_ko_cr.yaml#L8-L13) like this: `shp build create my-app --param-value go-version=1.23 --param-value go-flags=-mod=vendor`.
+The Shipwright CLI finally received the first support for [build parameters](../../../../../docs/build/build#defining-paramvalues). You can use the `--param-value` argument to provide values for strategy parameters such as the Go version and Go flags in our [ko sample build strategy](https://github.com/shipwright-io/build/blob/v0.14.0/samples/v1beta1/buildstrategy/ko/buildstrategy_ko_cr.yaml#L8-L13) like this: `shp build create my-app --param-value go-version=1.23 --param-value go-flags=-mod=vendor`.
 
 ### The smaller but still nice things
 
 Often the small changes are what help you, here are some:
 
 * If a step in your BuildRun goes out of memory, then it is now easier to determine that as the BuildRun status will have `StepOutOfMemory` as reason.
-* A [new sample build strategy](https://github.com/shipwright-io/build/blob/v0.14.0/samples/v1beta1/buildstrategy/multiarch-native-buildah/buildstrategy_multiarch_native_buildah_cr.yaml) has been added which orchestrates a multi-arch build using Kubernetes Jobs. See [our documentation](https://github.com/shipwright-io/build/blob/v0.14.0/docs/buildstrategies.md#multi-arch-native-buildah) for more information.
+* A [new sample build strategy](https://github.com/shipwright-io/build/blob/v0.14.0/samples/v1beta1/buildstrategy/multiarch-native-buildah/buildstrategy_multiarch_native_buildah_cr.yaml) has been added which orchestrates a multi-arch build using Kubernetes Jobs. See [our documentation](../../../../../docs/build/buildstrategies#multi-arch-native-buildah) for more information.
 * We started to implement node selection properties on Builds and BuildRuns with [node selector support](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector). Tolerations are planned to be added in v0.15.
 * As usual, we have done our due diligence. DependaBot helped us to keep our dependencies secure. We are now building with Go 1.22. Kubernetes and Tekton dependencies have been updated. We are also in the process of establishing automation across our repositories that gives us a GitHub issue once our latest release becomes vulnerable. You'll probably see more patch releases in the future where we keep our release free of vulnerabilities.
 

content/en/docs/build/authentication.md

@@ -1,14 +1,15 @@
 ---
 title: Authentication during builds
+weight: 40
 ---
 
 The following document provides an introduction around the different authentication methods that can take place during an image build when using the Build controller.
 
 - [Overview](#overview)
 - [Build Secrets Annotation](#build-secrets-annotation)
 - [Authentication for Git](#authentication-for-git)
-  - [Basic authentication](#basic-authentication)
   - [SSH authentication](#ssh-authentication)
+  - [Basic authentication](#basic-authentication)
   - [Usage of git secret](#usage-of-git-secret)
 - [Authentication to container registries](#authentication-to-container-registries)
   - [Docker Hub](#docker-hub)
@@ -17,7 +18,7 @@ The following document provides an introduction around the different authenticat
 
 ## Overview
 
-There are two places where users might need to define authentication when building images. Authentication to a container registry is the most common one, but also users might have the need to define authentications for pulling source-code from Git. Overall, the authentication is done via the definition of [secrets](https://kubernetes.io/docs/concepts/configuration/secret/) in which the require sensitive data will be stored.
+There are two places where users might need to define authentication when building images. Authentication to a container registry is the most common one, but also users might have the need to define authentications for pulling source-code from Git. Overall, the authentication is done via the definition of [secrets](https://kubernetes.io/docs/concepts/configuration/secret/) in which the required sensitive data will be stored.
 
 ## Build Secrets Annotation
 
@@ -74,7 +75,10 @@ data:
 The Basic authentication is very similar to the ssh one, but with the following differences:
 
 - The Kubernetes secret should be of the type `kubernetes.io/basic-auth`
-- The `stringData` should host your user and password in clear text.
+- The `stringData` should host your user and personal access token in clear text.
+
+Note: GitHub and GitLab no longer accept account passwords when authenticating Git operations.
+Instead, you must use token-based authentication for all authenticated Git operations. You can create your own personal access token on [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html).
 
 ```yaml
 apiVersion: v1
@@ -86,7 +90,7 @@ metadata:
 type: kubernetes.io/basic-auth
 stringData:
   username: <cleartext username>
-  password: <cleartext password>
+  password: <cleartext token>
 ```
 
 ### Usage of git secret
@@ -98,29 +102,29 @@ Depending on the secret type, there are two ways of doing this:
 When using ssh auth, users should follow:
 
 ```yaml
-apiVersion: shipwright.io/v1alpha1
+apiVersion: shipwright.io/v1beta1
 kind: Build
 metadata:
   name: buildah-golang-build
 spec:
   source:
-    url: git@gitlab.com:eduardooli/newtaxi.git
-    credentials:
-      name: secret-git-ssh-auth
+    git:
+      url: [email protected]:eduardooli/newtaxi.git
+      cloneSecret: secret-git-ssh-auth
 ```
 
 When using basic auth, users should follow:
 
 ```yaml
-apiVersion: shipwright.io/v1alpha1
+apiVersion: shipwright.io/v1beta1
 kind: Build
 metadata:
   name: buildah-golang-build
 spec:
   source:
-    url: https://gitlab.com/eduardooli/newtaxi.git
-    credentials:
-      name: secret-git-basic-auth
+    git:
+      url: https://gitlab.com/eduardooli/newtaxi.git
+      cloneSecret: secret-git-basic-auth
 ```
 
 ## Authentication to container registries
@@ -146,18 +150,17 @@ _Notes:_ The value of `PASSWORD` can be your user docker hub password, or an acc
 ### Usage of registry secret
 
 With the right secret in place (_note: Ensure creation of secret in the proper Kubernetes namespace_), users should reference it on their Build YAML definitions.
-For container registries, the secret should be placed under the `spec.output.credentials` path.
+For container registries, the secret should be placed under the `spec.output.pushSecret` path.
 
 ```yaml
-apiVersion: shipwright.io/v1alpha1
+apiVersion: shipwright.io/v1beta1
 kind: Build
 metadata:
   name: buildah-golang-build
   ...
   output:
     image: docker.io/foobar/sample:latest
-    credentials:
-      name: <CONTAINER_REGISTRY_SECRET_NAME>
+    pushSecret: <CONTAINER_REGISTRY_SECRET_NAME>
 ```
 
 ## References

content/en/docs/build/build.md

@@ -1,6 +1,6 @@
 ---
 title: Build
-weight: 10
+weight: 20
 ---
 <!--
 Copyright The Shipwright Contributors
@@ -15,12 +15,17 @@ SPDX-License-Identifier: Apache-2.0
   - [Defining the Source](#defining-the-source)
   - [Defining the Strategy](#defining-the-strategy)
   - [Defining ParamValues](#defining-paramvalues)
+    - [Example](#example)
   - [Defining the Builder or Dockerfile](#defining-the-builder-or-dockerfile)
   - [Defining the Output](#defining-the-output)
+  - [Defining the vulnerabilityScan](#defining-the-vulnerabilityscan)
   - [Defining Retention Parameters](#defining-retention-parameters)
   - [Defining Volumes](#defining-volumes)
   - [Defining Triggers](#defining-triggers)
-- [BuildRun deletion](#buildrun-deletion)
+    - [GitHub](#github)
+    - [Image](#image)
+    - [Tekton Pipeline](#tekton-pipeline)
+- [BuildRun Deletion](#buildrun-deletion)
 
 ## Overview
 
@@ -35,6 +40,7 @@ A `Build` resource allows the user to define:
 - env
 - retention
 - volumes
+- nodeSelector
 
 A `Build` is available within a namespace.
 
@@ -99,7 +105,7 @@ The `Build` definition supports the following fields:
   - [`kind`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) - Specifies the Kind type, for example `Build`.
   - [`metadata`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) - Metadata that identify the custom resource instance, especially the name of the `Build`, and in which [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) you place it. **Note**: You should use your own namespace, and not put your builds into the shipwright-build namespace where Shipwright's system components run.
   - `spec.source` - Refers to the location of the source code, for example a Git repository or OCI artifact image.
-  - `spec.strategy` - Refers to the `BuildStrategy` to be used, see the [examples](../samples/v1beta1/buildstrategy)
+  - `spec.strategy` - Refers to the `BuildStrategy` to be used, see the [examples](https://github.com/shipwright-io/build/tree/v0.14.0/samples/v1beta1/buildstrategy)
   - `spec.output`- Refers to the location where the generated image would be pushed.
   - `spec.output.pushSecret`- Reference an existing secret to get access to the container registry.
 
@@ -113,12 +119,14 @@ The `Build` definition supports the following fields:
     - Use string `SourceTimestamp` to set the image timestamp to the source timestamp, i.e. the timestamp of the Git commit that was used.
     - Use string `BuildTimestamp` to set the image timestamp to the timestamp of the build run.
     - Use any valid UNIX epoch seconds number as a string to set this as the image timestamp.
+  - `spec.output.vulnerabilityScan` to enable a security vulnerability scan for your generated image. Further options in vulnerability scanning are defined [here](#defining-the-vulnerabilityscan)
   - `spec.env` - Specifies additional environment variables that should be passed to the build container. The available variables depend on the tool that is being used by the chosen build strategy.
   - `spec.retention.atBuildDeletion` - Defines if all related BuildRuns needs to be deleted when deleting the Build. The default is false.
   - `spec.retention.ttlAfterFailed` - Specifies the duration for which a failed buildrun can exist.
   - `spec.retention.ttlAfterSucceeded` - Specifies the duration for which a successful buildrun can exist.
   - `spec.retention.failedLimit` - Specifies the number of failed buildrun that can exist.
   - `spec.retention.succeededLimit` - Specifies the number of successful buildrun can exist.
+  - `spec.nodeSelector` - Specifies a selector which must match a node's labels for the build pod to be scheduled on that node.
 
 ### Defining the Source
 
@@ -127,7 +135,7 @@ A `Build` resource can specify a source type, such as a Git repository or an OCI
 - `source.type` - Specify the type of the data-source. Currently, the supported types are "Git", "OCIArtifact", and "Local".
 - `source.git.url` - Specify the source location using a Git repository.
 - `source.git.cloneSecret` - For private repositories or registries, the name references a secret in the namespace that contains the SSH private key or Docker access credentials, respectively.
-- `source.git.revision` - A specific revision to select from the source repository, this can be a commit, tag or branch name. If not defined, it will fallback to the Git repository default branch.
+- `source.git.revision` - A specific revision to select from the source repository, this can be a commit, tag or branch name. If not defined, it will fall back to the Git repository default branch.
 - `source.contextDir` - For repositories where the source code is not located at the root folder, you can specify this path here.
 
 By default, the Build controller does not validate that the Git repository exists. If the validation is desired, users can explicitly define the `build.shipwright.io/verify.repository` annotation with `true`. For example:
@@ -262,12 +270,12 @@ spec:
 
 A `Build` resource can specify the `BuildStrategy` to use, these are:
 
-- [Buildah](buildstrategies.md#buildah)
-- [Buildpacks-v3](buildstrategies.md#buildpacks-v3)
-- [BuildKit](buildstrategies.md#buildkit)
-- [Kaniko](buildstrategies.md#kaniko)
-- [ko](buildstrategies.md#ko)
-- [Source-to-Image](buildstrategies.md#source-to-image)
+- [Buildah](../buildstrategies#buildah)
+- [Buildpacks-v3](../buildstrategies#buildpacks-v3)
+- [BuildKit](../buildstrategies#buildkit)
+- [Kaniko](../buildstrategies#kaniko)
+- [ko](../buildstrategies#ko)
+- [Source-to-Image](../buildstrategies#source-to-image)
 
 Defining the strategy is straightforward. You define the `name` and the `kind`. For example:
 
@@ -284,7 +292,7 @@ spec:
 
 ### Defining ParamValues
 
-A `Build` resource can specify _paramValues_ for parameters that are defined in the referenced `BuildStrategy`. You specify these parameter values to control how the steps of the build strategy behave. You can overwrite values in the `BuildRun` resource. See the related [documentation](./buildrun.md#defining-params) for more information.
+A `Build` resource can specify _paramValues_ for parameters that are defined in the referenced `BuildStrategy`. You specify these parameter values to control how the steps of the build strategy behave. You can overwrite values in the `BuildRun` resource. See the related [documentation](../buildrun#defining-paramvalues) for more information.
 
 The build strategy author can define a parameter as either a simple string or an array. Depending on that, you must specify the value accordingly. The build strategy parameter can be specified with a default value. You must specify a value in the `Build` or `BuildRun` for parameters without a default.
 
@@ -299,7 +307,7 @@ In general, _paramValues_ are tightly bound to Strategy _parameters_. Please mak
 
 #### Example
 
-The [BuildKit sample `BuildStrategy`](../samples/v1beta1/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml) contains various parameters. Two of them are outlined here:
+The [BuildKit sample `BuildStrategy`](https://github.com/shipwright-io/build/tree/v0.14.0/samples/v1beta1/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml) contains various parameters. Two of them are outlined here:
 
 ```yaml
 apiVersion: shipwright.io/v1beta1
@@ -594,6 +602,48 @@ spec:
     timestamp: SourceTimestamp
 ```
 
+### Defining the vulnerabilityScan
+
+`vulnerabilityScan` provides configurations to run a scan for your generated image.
+
+- `vulnerabilityScan.enabled` - Specify whether to run vulnerability scan for image. The supported values are true and false.
+- `vulnerabilityScan.failOnFinding` - indicates whether to fail the build run if the vulnerability scan results in vulnerabilities. The supported values are true and false. This field is optional and false by default.
+- `vulnerabilityScan.ignore.issues` - references the security issues to be ignored in vulnerability scan
+- `vulnerabilityScan.ignore.severity` - denotes the severity levels of security issues to be ignored, valid values are:
+  - `low`: it will exclude low severity vulnerabilities, displaying only medium, high and critical vulnerabilities
+  - `medium`: it will exclude low and medium severity vulnerabilities, displaying only high and critical vulnerabilities
+  - `high`: it will exclude low, medium and high severity vulnerabilities, displaying only the critical vulnerabilities
+- `vulnerabilityScan.ignore.unfixed` - indicates to ignore vulnerabilities for which no fix exists. The supported types are true and false.
+
+Example of user specified image vulnerability scanning options:
+
+```yaml
+apiVersion: shipwright.io/v1beta1
+kind: Build
+metadata:
+  name: sample-go-build
+spec:
+  source:
+    type: Git
+    git:
+      url: https://github.com/shipwright-io/sample-go
+    contextDir: source-build
+  strategy:
+    name: buildkit
+    kind: ClusterBuildStrategy
+  output:
+    image: some.registry.com/namespace/image:tag
+    pushSecret: credentials
+    vulnerabilityScan:
+      enabled: true
+      failOnFinding: true
+      ignore:
+        issues:
+          - CVE-2022-12345
+        severity: Low
+        unfixed: true
+```
+
 Annotations added to the output image can be verified by running the command:
 
 ```sh