diff --git a/content/en/docs/build/build.md b/content/en/docs/build/build.md index ede2cea3..953cf46e 100644 --- a/content/en/docs/build/build.md +++ b/content/en/docs/build/build.md @@ -19,21 +19,22 @@ SPDX-License-Identifier: Apache-2.0 - [Defining the Output](#defining-the-output) - [Defining Retention Parameters](#defining-retention-parameters) - [Defining Volumes](#defining-volumes) -- [BuildRun deletion](#BuildRun-deletion) + - [Defining Triggers](#defining-triggers) +- [BuildRun deletion](#buildrun-deletion) ## Overview A `Build` resource allows the user to define: - source -- sources +- trigger - strategy -- params -- builder -- dockerfile +- paramValues - output +- timeout - env - retention +- volumes A `Build` is available within a namespace. @@ -45,54 +46,75 @@ The controller watches for: When the controller reconciles it: -- Validates if the referenced `StrategyRef` exists. -- Validates if the specified `params` exist on the referenced strategy parameters. It also validates if the `params` names collide with the Shipwright reserved names. +- Validates if the referenced `Strategy` exists. +- Validates if the specified `paramValues` exist on the referenced strategy parameters. It also validates if the `paramValues` names collide with the Shipwright reserved names. - Validates if the container `registry` output secret exists. -- Validates if the referenced `spec.source.url` endpoint exists. +- Validates if the referenced `spec.source.git.url` endpoint exists. ## Build Validations -To prevent users from triggering `BuildRuns` (_execution of a Build_) that will eventually fail because of wrong or missing dependencies or configuration settings, the Build controller will validate them in advance. If all validations are successful, users can expect a `Succeeded` `status.reason`. However, if any validations fail, users can rely on the `status.reason` and `status.message` fields to understand the root cause. - -| Status.Reason | Description | -| --- | --- | -| BuildStrategyNotFound | The referenced namespace-scope strategy doesn't exist. | -| ClusterBuildStrategyNotFound | The referenced cluster-scope strategy doesn't exist. | -| SetOwnerReferenceFailed | Setting ownerreferences between a Build and a BuildRun failed. This status is triggered when using the `build.shipwright.io/build-run-deletion` annotation in a Build. | -| SpecSourceSecretRefNotFound | The secret used to authenticate to git doesn't exist. | -| SpecOutputSecretRefNotFound | The secret used to authenticate to the container registry doesn't exist. | -| SpecBuilderSecretRefNotFound | The secret used to authenticate the container registry doesn't exist.| -| MultipleSecretRefNotFound | More than one secret is missing. At the moment, only three paths on a Build can specify a secret. | -| RestrictedParametersInUse | One or many defined `params` are colliding with Shipwright reserved parameters. See [Defining Params](#defining-params) for more information. | -| UndefinedParameter | One or many defined `params` are not defined in the referenced strategy. Please ensure that the strategy defines them under its `spec.parameters` list. | -| RemoteRepositoryUnreachable | The defined `spec.source.url` was not found. This validation only takes place for HTTP/HTTPS protocols. | -| BuildNameInvalid | The defined `Build` name (`metadata.name`) is invalid. The `Build` name should be a [valid label value](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). | -| SpecEnvNameCanNotBeBlank | Indicates that the name for a user-provided environment variable is blank. | -| SpecEnvValueCanNotBeBlank | Indicates that the value for a user-provided environment variable is blank. | +**Note**: reported validations in build status are deprecated, and will be removed in a future release. + +To prevent users from triggering `BuildRun`s (_execution of a Build_) that will eventually fail because of wrong or missing dependencies or configuration settings, the Build controller will validate them in advance. If all validations are successful, users can expect a `Succeeded` `status.reason`. However, if any validations fail, users can rely on the `status.reason` and `status.message` fields to understand the root cause. + +| Status.Reason | Description | +|-------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| BuildStrategyNotFound | The referenced namespace-scope strategy doesn't exist. | +| ClusterBuildStrategyNotFound | The referenced cluster-scope strategy doesn't exist. | +| SetOwnerReferenceFailed | Setting ownerreferences between a Build and a BuildRun failed. This status is triggered when you set the `spec.retention.atBuildDeletion` to true in a Build. | +| SpecSourceSecretRefNotFound | The secret used to authenticate to git doesn't exist. | +| SpecOutputSecretRefNotFound | The secret used to authenticate to the container registry doesn't exist. | +| SpecBuilderSecretRefNotFound | The secret used to authenticate the container registry doesn't exist. | +| MultipleSecretRefNotFound | More than one secret is missing. At the moment, only three paths on a Build can specify a secret. | +| RestrictedParametersInUse | One or many defined `paramValues` are colliding with Shipwright reserved parameters. See [Defining Params](#defining-paramvalues) for more information. | +| UndefinedParameter | One or many defined `paramValues` are not defined in the referenced strategy. Please ensure that the strategy defines them under its `spec.parameters` list. | +| RemoteRepositoryUnreachable | The defined `spec.source.git.url` was not found. This validation only takes place for HTTP/HTTPS protocols. | +| BuildNameInvalid | The defined `Build` name (`metadata.name`) is invalid. The `Build` name should be a [valid label value](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). | +| SpecEnvNameCanNotBeBlank | The name for a user-provided environment variable is blank. | +| SpecEnvValueCanNotBeBlank | The value for a user-provided environment variable is blank. | +| SpecEnvOnlyOneOfValueOrValueFromMustBeSpecified | Both value and valueFrom were specified, which are mutually exclusive. | +| RuntimePathsCanNotBeEmpty | The `spec.runtime` feature is used but the paths were not specified. | +| WrongParameterValueType | A single value was provided for an array parameter, or vice-versa. | +| InconsistentParameterValues | Parameter values have more than one of _configMapValue_, _secretValue_, or _value_ set. | +| EmptyArrayItemParameterValues | Array parameters contain an item where none of _configMapValue_, _secretValue_, or _value_ is set. | +| IncompleteConfigMapValueParameterValues | A _configMapValue_ is specified where the name or the key is empty. | +| IncompleteSecretValueParameterValues | A _secretValue_ is specified where the name or the key is empty. | +| VolumeDoesNotExist | Volume referenced by the Build does not exist, therefore Build cannot be run. | +| VolumeNotOverridable | Volume defined by build is not set as overridable in the strategy. | +| UndefinedVolume | Volume defined by build is not found in the strategy. | +| TriggerNameCanNotBeBlank | Trigger condition does not have a name. | +| TriggerInvalidType | Trigger type is invalid. | +| TriggerInvalidGitHubWebHook | Trigger type GitHub is invalid. | +| TriggerInvalidImage | Trigger type Image is invalid. | +| TriggerInvalidPipeline | Trigger type Pipeline is invalid. | +| OutputTimestampNotSupported | An unsupported output timestamp setting was used. | +| OutputTimestampNotValid | The output timestamp value is not valid. | ## Configuring a Build The `Build` definition supports the following fields: - Required: - - [`apiVersion`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) - Specifies the API version, for example `shipwright.io/v1alpha1`. + - [`apiVersion`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) - Specifies the API version, for example `shipwright.io/v1beta1`. - [`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 CRD instance, for example the name of the `Build`. - - `spec.source` - Refers to the location of the source code, for example a Git repository or source bundle image. - - `spec.strategy` - Refers to the `BuildStrategy` to be used, see the [examples](../samples/buildstrategy) - - `spec.builder.image` - Refers to the image containing the build tools to build the source code. (_Use this path for Dockerless strategies, this is just required for `source-to-image` buildStrategy_) + - [`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.output`- Refers to the location where the generated image would be pushed. - - `spec.output.credentials.name`- Reference an existing secret to get access to the container registry. + - `spec.output.pushSecret`- Reference an existing secret to get access to the container registry. - Optional: - `spec.paramValues` - Refers to a name-value(s) list to specify values for `parameters` defined in the `BuildStrategy`. - - `spec.dockerfile` - Path to a Dockerfile to be used for building an image. (_Use this path for strategies that require a Dockerfile_) - - `spec.sources` - [Sources](#Sources) describes a slice of artifacts that will be imported into the project context before the actual build process starts. - `spec.timeout` - Defines a custom timeout. The value needs to be parsable by [ParseDuration](https://golang.org/pkg/time/#ParseDuration), for example, `5m`. The default is ten minutes. You can overwrite the value in the `BuildRun`. - - `metadata.annotations[build.shipwright.io/build-run-deletion]` - Defines if delete all related BuildRuns when deleting the Build. The default is `false`. - `spec.output.annotations` - Refers to a list of `key/value` that could be used to [annotate](https://github.com/opencontainers/image-spec/blob/main/annotations.md) the output image. - `spec.output.labels` - Refers to a list of `key/value` that could be used to label the output image. + - `spec.output.timestamp` - Instruct the build to change the output image creation timestamp to the specified value. When omitted, the respective build strategy tool defines the output image timestamp. + - Use string `Zero` to set the image timestamp to UNIX epoch timestamp zero. + - 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.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. @@ -100,21 +122,20 @@ The `Build` definition supports the following fields: ### Defining the Source -A `Build` resource can specify a Git repository or bundle image source, together with other parameters like: +A `Build` resource can specify a source type, such as a Git repository or an OCI artifact, together with other parameters like: -- `source.url` - Specify the source location using a Git repository. -- `source.bundleContainer.image` - Specify a source bundle container image to be used as the source. -- `source.bundleContainer.prune` - Configure whether the source bundle image should be deleted after the source was obtained (defaults to `Never`, other option is `AfterPull` to delete the image after a successful image pull). -- `source.credentials.name` - 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.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.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.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: -Example of a `Build` with the **build.shipwright.io/verify.repository** annotation to enable the `spec.source.url` validation. +Example of a `Build` with the **build.shipwright.io/verify.repository** annotation to enable the `spec.source.git.url` validation. ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build @@ -122,63 +143,72 @@ metadata: build.shipwright.io/verify.repository: "true" spec: source: - url: https://github.com/shipwright-io/sample-go + type: Git + git: + url: https://github.com/shipwright-io/sample-go contextDir: docker-build ``` -_Note_: The Build controller only validates two scenarios. The first one is when the endpoint uses an `http/https` protocol. The second one is when an `ssh` protocol such as `git@` has been defined but a referenced secret, such as `source.credentials.name`, has not been provided. +**Note**: The Build controller only validates two scenarios. The first one is when the endpoint uses an `http/https` protocol. The second one is when an `ssh` protocol such as `git@` has been defined but a referenced secret, such as `source.git.cloneSecret`, has not been provided. Example of a `Build` with a source with **credentials** defined by the user. ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildpack-nodejs-build spec: source: - url: https://github.com/sclorg/nodejs-ex - credentials: - name: source-repository-credentials + type: Git + git: + url: https://github.com/sclorg/nodejs-ex + cloneSecret: source-repository-credentials ``` Example of a `Build` with a source that specifies a specific subfolder on the repository. ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-custom-context-dockerfile spec: source: - url: https://github.com/SaschaSchwarze0/npm-simple + type: Git + git: + url: https://github.com/SaschaSchwarze0/npm-simple contextDir: renamed ``` -Example of a `Build` that specifies the tag `v.0.1.0` for the git repository: +Example of a `Build` that specifies the tag `v0.1.0` for the git repository: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: - url: https://github.com/shipwright-io/sample-go + type: Git + git: + url: https://github.com/shipwright-io/sample-go + revision: v0.1.0 contextDir: docker-build - revision: v0.1.0 ``` Example of a `Build` that specifies environment variables: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: - url: https://github.com/shipwright-io/sample-go + type: Git + git: + url: https://github.com/shipwright-io/sample-go contextDir: docker-build env: - name: EXAMPLE_VAR_1 @@ -187,17 +217,18 @@ spec: value: "example-value-2" ``` -Example of a `Build` that uses the Kubernetes Downward API to -expose a `Pod` field as an environment variable: +Example of a `Build` that uses the Kubernetes Downward API to expose a `Pod` field as an environment variable: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: - url: https://github.com/shipwright-io/sample-go + type: Git + git: + url: https://github.com/shipwright-io/sample-go contextDir: docker-build env: - name: POD_NAME @@ -206,17 +237,18 @@ spec: fieldPath: metadata.name ``` -Example of a `Build` that uses the Kubernetes Downward API to -expose a `Container` field as an environment variable: +Example of a `Build` that uses the Kubernetes Downward API to expose a `Container` field as an environment variable: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: - url: https://github.com/shipwright-io/sample-go + type: Git + git: + url: https://github.com/shipwright-io/sample-go contextDir: docker-build env: - name: MEMORY_LIMIT @@ -240,7 +272,7 @@ A `Build` resource can specify the `BuildStrategy` to use, these are: Defining the strategy is straightforward. You define the `name` and the `kind`. For example: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildpack-nodejs-build @@ -267,10 +299,10 @@ In general, _paramValues_ are tightly bound to Strategy _parameters_. Please mak #### Example -The [BuildKit sample `BuildStrategy`](../samples/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml) contains various parameters. Two of them are outlined here: +The [BuildKit sample `BuildStrategy`](../samples/v1beta1/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml) contains various parameters. Two of them are outlined here: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: buildkit @@ -286,14 +318,14 @@ spec: type: string default: registry ... - buildSteps: + steps: ... ``` The `cache` parameter is a simple string. You can provide it like this in your Build: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: a-build @@ -326,7 +358,7 @@ data: You reference the ConfigMap as a parameter value like this: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: a-build @@ -349,7 +381,7 @@ spec: The `build-args` parameter is defined as an array. In the BuildKit strategy, you use `build-args` to set the [`ARG` values in the Dockerfile](https://docs.docker.com/engine/reference/builder/#arg), specified as key-value pairs separated by an equals sign, for example, `NODE_VERSION=16`. Your Build then looks like this (the value for `cache` is retained to outline how multiple _paramValue_ can be set): ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: a-build @@ -375,7 +407,7 @@ spec: Like simple values, you can also reference ConfigMaps and Secrets for every item in the array. Example: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: a-build @@ -412,67 +444,77 @@ Here, we pass three items in the `build-args` array: 2. The second item is just a hard-coded value. 3. The third item references a Secret, the same as with ConfigMaps. -**NOTE**: The logging output of BuildKit contains expanded `ARG`s in `RUN` commands. Also, such information ends up in the final container image if you use such args in the [final stage of your Dockerfile](https://docs.docker.com/develop/develop-images/multistage-build/). An alternative approach to pass secrets is using [secret mounts](https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information). The BuildKit sample strategy supports them using the `secrets` parameter. +**Note**: The logging output of BuildKit contains expanded `ARG`s in `RUN` commands. Also, such information ends up in the final container image if you use such args in the [final stage of your Dockerfile](https://docs.docker.com/develop/develop-images/multistage-build/). An alternative approach to pass secrets is using [secret mounts](https://docs.docker.com/develop/develop-images/build_enhancements/#new-docker-build-secret-information). The BuildKit sample strategy supports them using the `secrets` parameter. ### Defining the Builder or Dockerfile -In the `Build` resource, you use the `spec.builder` or `spec.dockerfile` parameters to specify the image that contains the tools to build the final image. For example, the following Build definition specifies a `Dockerfile` image. +In the `Build` resource, you use the parameters (`spec.paramValues`) to specify the image that contains the tools to build the final image. For example, the following Build definition specifies a `Dockerfile` image. ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: - url: https://github.com/shipwright-io/sample-go + type: Git + git: + url: https://github.com/shipwright-io/sample-go contextDir: docker-build strategy: name: buildah kind: ClusterBuildStrategy - dockerfile: Dockerfile + paramValues: + - name: dockerfile + value: Dockerfile ``` Another example is when the user chooses the `builder` image for a specific language as part of the `source-to-image` buildStrategy: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: s2i-nodejs-build spec: source: - url: https://github.com/shipwright-io/sample-nodejs + type: Git + git: + url: https://github.com/shipwright-io/sample-nodejs contextDir: source-build/ strategy: name: source-to-image kind: ClusterBuildStrategy - builder: - image: docker.io/centos/nodejs-10-centos7 + paramValues: + - name: builder-image + value: "docker.io/centos/nodejs-10-centos7" ``` ### Defining the Output -A `Build` resource can specify the output where it should push the image. For external private registries, it is recommended to specify a secret with the related data to access it. An option is available to specify the annotation and labels for the output image. The annotations and labels mentioned here are specific to the container image and do not relate to the `Build` annotations. +A `Build` resource can specify the output where it should push the image. For external private registries, it is recommended to specify a secret with the related data to access it. An option is available to specify the annotation and labels for the output image. The annotations and labels mentioned here are specific to the container image and do not relate to the `Build` annotations. Analogous, the timestamp refers to the timestamp of the output image. -**NOTE**: When you specify annotations or labels, the output image will get pushed twice. The first push comes from the build strategy. Then, a follow-on update changes the image configuration to add the annotations and labels. If you have automation based on push events in your container registry, be aware of this behavior. +**Note**: When you specify annotations, labels, or timestamp, the output image **may** get pushed twice, depending on the respective strategy. For example, strategies that push the image to the registry as part of their build step will lead to an additional push of the image in case image processing like labels is configured. If you have automation based on push events in your container registry, be aware of this behavior. For example, the user specifies a public registry: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: s2i-nodejs-build spec: source: - url: https://github.com/shipwright-io/sample-nodejs + type: Git + git: + url: https://github.com/shipwright-io/sample-nodejs contextDir: source-build/ strategy: name: source-to-image kind: ClusterBuildStrategy - builder: - image: docker.io/centos/nodejs-10-centos7 + paramValues: + - name: builder-image + value: "docker.io/centos/nodejs-10-centos7" output: image: image-registry.openshift-image-registry.svc:5000/build-examples/nodejs-ex ``` @@ -480,45 +522,48 @@ spec: Another example is when the user specifies a private registry: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: s2i-nodejs-build spec: source: - url: https://github.com/shipwright-io/sample-nodejs + git: + url: https://github.com/shipwright-io/sample-nodejs contextDir: source-build/ strategy: name: source-to-image kind: ClusterBuildStrategy - builder: - image: docker.io/centos/nodejs-10-centos7 + paramValues: + - name: builder-image + value: "docker.io/centos/nodejs-10-centos7" output: image: us.icr.io/source-to-image-build/nodejs-ex - credentials: - name: icr-knbuild + pushSecret: icr-knbuild ``` Example of user specifies image annotations and labels: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: s2i-nodejs-build spec: source: - url: https://github.com/shipwright-io/sample-nodejs + type: Git + git: + url: https://github.com/shipwright-io/sample-nodejs contextDir: source-build/ strategy: name: source-to-image kind: ClusterBuildStrategy - builder: - image: docker.io/centos/nodejs-10-centos7 + paramValues: + - name: builder-image + value: "docker.io/centos/nodejs-10-centos7" output: image: us.icr.io/source-to-image-build/nodejs-ex - credentials: - name: icr-knbuild + pushSecret: icr-knbuild annotations: "org.opencontainers.image.source": "https://github.com/org/repo" "org.opencontainers.image.url": "https://my-company.com/images" @@ -527,16 +572,38 @@ spec: "description": "This is my cool image" ``` +Example of user specified image timestamp set to `SourceTimestamp` to set the output timestamp to match the timestamp of the Git commit used for the build: + +```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 + timestamp: SourceTimestamp +``` + Annotations added to the output image can be verified by running the command: ```sh - docker manifest inspect us.icr.io/source-to-image-build/nodejs-ex | jq ".annotations" +docker manifest inspect us.icr.io/source-to-image-build/nodejs-ex | jq ".annotations" ``` You can verify which labels were added to the output image that is available on the host machine by running the command: ```sh - docker inspect us.icr.io/source-to-image-build/nodejs-ex | jq ".[].Config.Labels" +docker inspect us.icr.io/source-to-image-build/nodejs-ex | jq ".[].Config.Labels" ``` ### Defining Retention Parameters @@ -545,6 +612,7 @@ A `Build` resource can specify how long a completed BuildRun can exist and the n As part of the retention parameters, we have the following fields: +- `retention.atBuildDeletion` - Defines if all related BuildRuns needs to be deleted when deleting the Build. The default is false. - `retention.succeededLimit` - Defines number of succeeded BuildRuns for a Build that can exist. - `retention.failedLimit` - Defines number of failed BuildRuns for a Build that can exist. - `retention.ttlAfterFailed` - Specifies the duration for which a failed buildrun can exist. @@ -553,13 +621,15 @@ As part of the retention parameters, we have the following fields: An example of a user using both TTL and Limit retention fields. In case of such a configuration, BuildRun will get deleted once the first criteria is met. ```yaml - apiVersion: shipwright.io/v1alpha1 + apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: build-retention-ttl spec: source: - url: "https://github.com/shipwright-io/sample-go" + type: Git + git: + url: "https://github.com/shipwright-io/sample-go" contextDir: docker-build strategy: kind: ClusterBuildStrategy @@ -572,30 +642,34 @@ An example of a user using both TTL and Limit retention fields. In case of such succeededLimit: 20 ``` -**NOTE**: When changes are made to `retention.failedLimit` and `retention.succeededLimit` values, they come into effect as soon as the build is applied, thereby enforcing the new limits. On the other hand, changing the `retention.ttlAfterFailed` and `retention.ttlAfterSucceeded` values will only affect new buildruns. Old buildruns will adhere to the old TTL retention values. In case TTL values are defined in buildrun specifications as well as build specifications, priority will be given to the values defined in the buildrun specifications. +**Note**: When changes are made to `retention.failedLimit` and `retention.succeededLimit` values, they come into effect as soon as the build is applied, thereby enforcing the new limits. On the other hand, changing the `retention.ttlAfterFailed` and `retention.ttlAfterSucceeded` values will only affect new buildruns. Old buildruns will adhere to the old TTL retention values. In case TTL values are defined in buildrun specifications as well as build specifications, priority will be given to the values defined in the buildrun specifications. ### Defining Volumes `Builds` can declare `volumes`. They must override `volumes` defined by the according `BuildStrategy`. If a `volume` is not `overridable` then the `BuildRun` will eventually fail. -`Volumes` follow the declaration of [Pod Volumes](https://kubernetes.io/docs/concepts/storage/volumes/), so +`Volumes` follow the declaration of [Pod Volumes](https://kubernetes.io/docs/concepts/storage/volumes/), so all the usual `volumeSource` types are supported. Here is an example of `Build` object that overrides `volumes`: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: build-name spec: source: - url: https://github.com/example/url + type: Git + git: + url: https://github.com/example/url strategy: name: buildah kind: ClusterBuildStrategy - dockerfile: Dockerfile + paramValues: + - name: dockerfile + value: Dockerfile output: image: registry/namespace/image:latest volumes: @@ -604,41 +678,122 @@ spec: name: test-config ``` -### Sources +### Defining Triggers + +Using the triggers, you can submit `BuildRun` instances when certain events happen. The idea is to be able to trigger Shipwright builds in an event driven fashion, for that purpose you can watch certain types of events. -Sources represent remote artifacts, as in external entities added to the build context before the actual Build starts. Therefore, you may employ `.spec.sources` to download artifacts from external repositories. +**Note**: triggers rely on the [Shipwright Triggers](https://github.com/shipwright-io/triggers) project to be deployed and configured in the same Kubernetes cluster where you run Shipwright Build. If it is not set up, the triggers defined in a Build are ignored. + +The types of events under watch are defined on the `.spec.trigger` attribute, please consider the following example: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build -metadata: - name: nodejs-ex spec: - sources: - - name: project-logo - url: https://gist.github.com/project/image.png + source: + type: Git + git: + url: https://github.com/shipwright-io/sample-go + cloneSecret: webhook-secret + contextDir: docker-build + trigger: + when: [] ``` -Under `.spec.sources` are the following attributes: +Certain types of events will use attributes defined on `.spec.source` to complete the information needed in order to dispatch events. -- `.name`: represents the name of the resource, required attribute. -- `.url`: universal resource location (URL), required attribute. +#### GitHub -When downloading artifacts, the process is executed in the same directory where the application source-code is located, by default `/workspace/source`. +The GitHub type is meant to react upon events coming from GitHub WebHook interface, the events are compared against the existing `Build` resources, and therefore it can identify the `Build` objects based on `.spec.source.git.url` combined with the attributes on `.spec.trigger.when[].github`. -Additionally, we plan to keep evolving `.spec.sources` by adding more types of remote data declaration. This API field works as an extension point to support external and internal resource locations. +To identify a given `Build` object, the first criteria is the repository URL, and then the branch name listed on the GitHub event payload must also match. Following the criteria: -At this initial stage, authentication is not supported; therefore, you can only download from sources without this mechanism in place. +- First, the branch name is checked against the `.spec.trigger.when[].github.branches` entries +- If the `.spec.trigger.when[].github.branches` is empty, the branch name is compared against `.spec.source.git.revision` +- If `spec.source.git.revision` is empty, the default revision name is used ("main") -## BuildRun deletion +The following snippet shows a configuration matching `Push` and `PullRequest` events on the `main` branch, for example: -A `Build` can automatically delete a related `BuildRun`. To enable this feature set the `build.shipwright.io/build-run-deletion` annotation to `true` in the `Build` instance. This annotation is not present in a `Build` definition by default. See an example of how to define this annotation: +```yaml +# [...] +spec: + source: + git: + url: https://github.com/shipwright-io/sample-go + trigger: + when: + - name: push and pull-request on the main branch + type: GitHub + github: + events: + - Push + - PullRequest + branches: + - main +``` + +#### Image + +In order to watch over images, in combination with the [Image](https://github.com/shipwright-io/image) controller, you can trigger new builds when those container image names change. + +For instance, lets imagine the image named `ghcr.io/some/base-image` is used as input for the Build process and every time it changes we would like to trigger a new build. Please consider the following snippet: + +```yaml +# [...] +spec: + trigger: + when: + - name: watching for the base-image changes + type: Image + image: + names: + - ghcr.io/some/base-image:latest +``` + +#### Tekton Pipeline + +Shipwright can also be used in combination with [Tekton Pipeline](https://github.com/tektoncd/pipeline), you can configure the Build to watch for `Pipeline` resources in Kubernetes reacting when the object reaches the desired status (`.objectRef.status`), and is identified either by its name (`.objectRef.name`) or a label selector (`.objectRef.selector`). The example below uses the label selector approach: + +```yaml +# [...] +spec: + trigger: + when: + - name: watching over for the Tekton Pipeline + type: Pipeline + objectRef: + status: + - Succeeded + selector: + label: value +``` + +While the next snippet uses the object name for identification: + +```yaml +# [...] +spec: + trigger: + when: + - name: watching over for the Tekton Pipeline + type: Pipeline + objectRef: + status: + - Succeeded + name: tekton-pipeline-name +``` + +## BuildRun Deletion + +A `Build` can automatically delete a related `BuildRun`. To enable this feature set the `spec.retention.atBuildDeletion` to `true` in the `Build` instance. The default value is set to `false`. See an example of how to define this field: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: kaniko-golang-build - annotations: - build.shipwright.io/build-run-deletion: "true" +spec: + retention: + atBuildDeletion: true + # [...] ``` diff --git a/content/en/docs/build/buildrun.md b/content/en/docs/build/buildrun.md index 60875414..999a9a2c 100644 --- a/content/en/docs/build/buildrun.md +++ b/content/en/docs/build/buildrun.md @@ -12,8 +12,8 @@ SPDX-License-Identifier: Apache-2.0 - [Overview](#overview) - [BuildRun Controller](#buildrun-controller) - [Configuring a BuildRun](#configuring-a-buildrun) - - [Defining the BuildRef](#defining-the-buildref) - - [Defining the BuildSpec](#defining-the-buildspec) + - [Defining the Build Reference](#defining-the-build-reference) + - [Defining the Build Specification](#defining-the-build-specification) - [Defining ParamValues](#defining-paramvalues) - [Defining the ServiceAccount](#defining-the-serviceaccount) - [Defining Retention Parameters](#defining-retention-parameters) @@ -31,7 +31,7 @@ SPDX-License-Identifier: Apache-2.0 ## Overview -The resource `BuildRun` (`buildruns.shipwright.io/v1alpha1`) is the build process of a `Build` resource definition executed in Kubernetes. +The resource `BuildRun` (`buildruns.shipwright.io/v1beta1`) is the build process of a `Build` resource definition executed in Kubernetes. A `BuildRun` resource allows the user to define: @@ -60,55 +60,78 @@ When the controller reconciles it: The `BuildRun` definition supports the following fields: - Required: - - [`apiVersion`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) - Specifies the API version, for example `shipwright.io/v1alpha1`. + - [`apiVersion`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) - Specifies the API version, for example `shipwright.io/v1beta1`. - [`kind`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) - Specifies the Kind type, for example `BuildRun`. - [`metadata`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) - Metadata that identify the CRD instance, for example the name of the `BuildRun`. - Optional: - - `spec.buildRef` - Specifies an existing `Build` resource instance to use. It cannot be used together with `buildSpec`. - - `spec.buildSpec` - Specifies an embedded (transient) Build resource to use. It cannot be used together with `buildRef`. + - `spec.build.name` - Specifies an existing `Build` resource instance to use. + - `spec.build.spec` - Specifies an embedded (transient) Build resource to use. - `spec.serviceAccount` - Refers to the SA to use when building the image. (_defaults to the `default` SA_) - `spec.timeout` - Defines a custom timeout. The value needs to be parsable by [ParseDuration](https://golang.org/pkg/time/#ParseDuration), for example, `5m`. The value overwrites the value that is defined in the `Build`. - `spec.paramValues` - Refers to a name-value(s) list to specify values for `parameters` defined in the `BuildStrategy`. This value overwrites values defined with the same name in the Build. - - `spec.output.image` - Refers to a custom location where the generated image would be pushed. The value will overwrite the `output.image` value defined in `Build`. ( Note: other properties of the output, for example, the credentials, cannot be specified in the buildRun spec. ) - - `spec.output.credentials.name` - Reference an existing secret to get access to the container registry. This secret will be added to the service account along with the ones requested by the `Build`. + - `spec.output.image` - Refers to a custom location where the generated image would be pushed. The value will overwrite the `output.image` value defined in `Build`. (**Note**: other properties of the output, for example, the credentials, cannot be specified in the buildRun spec. ) + - `spec.output.pushSecret` - Reference an existing secret to get access to the container registry. This secret will be added to the service account along with the ones requested by the `Build`. + - `spec.output.timestamp` - Overrides the output timestamp configuration of the referenced build to instruct the build to change the output image creation timestamp to the specified value. When omitted, the respective build strategy tool defines the output image timestamp. - `spec.env` - Specifies additional environment variables that should be passed to the build container. Overrides any environment variables that are specified in the `Build` resource. The available variables depend on the tool used by the chosen build strategy. -_Note:_ The `BuildRef` and `BuildSpec` are mutually exclusive. Furthermore, the overrides for `timeout`, `paramValues`, `output`, and `env` can only be combined with `buildRef`, but **not** with `buildSpec`. +**Note**: The `spec.build.name` and `spec.build.spec` are mutually exclusive. Furthermore, the overrides for `timeout`, `paramValues`, `output`, and `env` can only be combined with `spec.build.name`, but **not** with `spec.build.spec`. -### Defining the BuildRef +### Defining the Build Reference A `BuildRun` resource can reference a `Build` resource, that indicates what image to build. For example: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced spec: - buildRef: + build: name: buildpack-nodejs-build-namespaced ``` -### Defining the BuildSpec +### Defining the Build Specification -Alternatively to `BuildRef`, a complete `BuildSpec` can be embedded into the `BuildRun` for the build. +A complete `BuildSpec` can be embedded into the `BuildRun` for the build. ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: standalone-buildrun spec: - buildSpec: - source: - url: https://github.com/shipwright-io/sample-go.git - contextDir: source-build - strategy: - kind: ClusterBuildStrategy - name: buildpacks-v3 - output: - image: foo/bar:latest + build: + spec: + source: + type: Git + git: + url: https://github.com/shipwright-io/sample-go.git + contextDir: source-build + strategy: + kind: ClusterBuildStrategy + name: buildpacks-v3 + output: + image: foo/bar:latest +``` + +### Defining the Build Source + +BuildRun's support the specification of a Local type source. This is useful for working on development mode, without forcing a user to commit/push changes to their related version control system. For more information please refer to [SHIP 0016 - enabling local source code](https://github.com/shipwright-io/community/blob/main/ships/0016-enable-local-source-code-support.md). + +```yaml +apiVersion: shipwright.io/v1beta1 +kind: BuildRun +metadata: + name: local-buildrun +spec: + build: + name: a-build + source: + type: Local + local: + name: local-source + timeout: 3m ``` ### Defining ParamValues @@ -119,7 +142,7 @@ For example, the following `BuildRun` overrides the value for _sleep-time_ param ```yaml --- -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: a-build @@ -137,13 +160,13 @@ spec: ... --- -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: a-buildrun namespace: a-namespace spec: - buildRef: + build: name: a-build paramValues: - name: cache @@ -157,20 +180,19 @@ See more about _paramValues_ usage in the related [Build](./build.md#defining-pa A `BuildRun` resource can define a serviceaccount to use. Usually this SA will host all related secrets referenced on the `Build` resource, for example: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced spec: - buildRef: + build: name: buildpack-nodejs-build-namespaced - serviceAccount: - name: pipeline + serviceAccount: pipeline ``` -You can also use set the `spec.serviceAccount.generate` path to `true`. This will generate the service account during runtime for you. The name of the generated service account is the name of the BuildRun. +You can also set the value of `spec.serviceAccount` to `".generate"`. This will generate the service account during runtime for you. The name of the generated service account is the same as that of the BuildRun. -_**Note**_: When the service account is not defined, the `BuildRun` uses the `pipeline` service account if it exists in the namespace, and falls back to the `default` service account. +**Note**: When the service account is not defined, the `BuildRun` uses the `pipeline` service account if it exists in the namespace, and falls back to the `default` service account. ### Defining Retention Parameters @@ -184,40 +206,37 @@ As part of the buildrun retention parameters, we have the following fields: An example of a user using buildrun TTL parameters. ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buidrun-retention-ttl spec: - buildRef: + build: name: build-retention-ttl retention: ttlAfterFailed: 10m ttlAfterSucceeded: 10m ``` -**NOTE** In case TTL values are defined in buildrun specifications as well as build specifications, priority will be given to the values defined in the buildrun specifications. +**Note**: In case TTL values are defined in buildrun specifications as well as build specifications, priority will be given to the values defined in the buildrun specifications. ### Defining Volumes -`BuildRuns` can declare `volumes`. They must override `volumes` defined by the according `BuildStrategy`. If a `volume` -is not `overridable` then the `BuildRun` will eventually fail. +`BuildRuns` can declare `volumes`. They must override `volumes` defined by the according `BuildStrategy`. If a `volume` is not `overridable` then the `BuildRun` will eventually fail. -In case `Build` and `BuildRun` that refers to this `Build` override the same `volume`, one that is defined in the `BuildRun` -is the one used eventually. +In case `Build` and `BuildRun` that refers to this `Build` override the same `volume`, one that is defined in the `BuildRun` is the one used eventually. -`Volumes` follow the declaration of [Pod Volumes](https://kubernetes.io/docs/concepts/storage/volumes/), so -all the usual `volumeSource` types are supported. +`Volumes` follow the declaration of [Pod Volumes](https://kubernetes.io/docs/concepts/storage/volumes/), so all the usual `volumeSource` types are supported. Here is an example of `BuildRun` object that overrides `volumes`: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildrun-name spec: - buildRef: + build: name: build-name volumes: - name: volume-name @@ -234,7 +253,7 @@ When you cancel a `BuildRun`, the underlying `TaskRun` is marked as canceled per Example of canceling a `BuildRun`: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced @@ -250,7 +269,7 @@ We have two controllers that ensure that buildruns can be deleted automatically - Buildrun TTL parameters: These are used to make sure that buildruns exist for a fixed duration of time after completiion. - `buildrun.spec.retention.ttlAfterFailed`: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has failed. - `buildrun.spec.retention.ttlAfterSucceeded`: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has succeeded. -- Build TTL parameters: These are used to make sure that related buildruns exist for a fixed duration of time after completiion. +- Build TTL parameters: These are used to make sure that related buildruns exist for a fixed duration of time after completion. - `build.spec.retention.ttlAfterFailed`: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has failed. - `build.spec.retention.ttlAfterSucceeded`: The buildrun is deleted if the mentioned duration of time has passed and the buildrun has succeeded. - Build Limit parameters: These are used to make sure that related buildruns exist for a fixed duration of time after completiion. @@ -262,12 +281,12 @@ We have two controllers that ensure that buildruns can be deleted automatically An example of a `BuildRun` that specifies environment variables: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced spec: - buildRef: + build: name: buildpack-nodejs-build-namespaced env: - name: EXAMPLE_VAR_1 @@ -276,16 +295,15 @@ spec: value: "example-value-2" ``` -Example of a `BuildRun` that uses the Kubernetes Downward API to -expose a `Pod` field as an environment variable: +Example of a `BuildRun` that uses the Kubernetes Downward API to expose a `Pod` field as an environment variable: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced spec: - buildRef: + build: name: buildpack-nodejs-build-namespaced env: - name: POD_NAME @@ -294,16 +312,15 @@ spec: fieldPath: metadata.name ``` -Example of a `BuildRun` that uses the Kubernetes Downward API to -expose a `Container` field as an environment variable: +Example of a `BuildRun` that uses the Kubernetes Downward API to expose a `Container` field as an environment variable: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildpack-nodejs-buildrun-namespaced spec: - buildRef: + build: name: buildpack-nodejs-build-namespaced env: - name: MEMORY_LIMIT @@ -345,50 +362,48 @@ The `status.conditions` hosts different fields, like `status`, `reason` and `mes The following table illustrates the different states a BuildRun can have under its `status.conditions`: -| Status | Reason | CompletionTime is set | Description | -| --- | --- | --- | --- | -| Unknown | Pending | No | The BuildRun is waiting on a Pod in status Pending. | -| Unknown | Running | No | The BuildRun has been validated and started to perform its work. | -| Unknown | Running | No | The BuildRun has been validated and started to perform its work. | -| Unknown | BuildRunCanceled | No | The user requested the BuildRun to be canceled. This results in the BuildRun controller requesting the TaskRun be canceled. Cancellation has not been done yet. | -| True | Succeeded | Yes | The BuildRun Pod is done. | -| False | Failed | Yes | The BuildRun failed in one of the steps. | -| False | BuildRunTimeout | Yes | The BuildRun timed out. | -| False | UnknownStrategyKind | Yes | The Build specified strategy Kind is unknown. (_options: ClusterBuildStrategy or BuildStrategy_) | -| False | ClusterBuildStrategyNotFound | Yes | The referenced cluster strategy was not found in the cluster. | -| False | BuildStrategyNotFound | Yes | The referenced namespaced strategy was not found in the cluster. | -| False | SetOwnerReferenceFailed | Yes | Setting ownerreferences from the BuildRun to the related TaskRun failed. | -| False | TaskRunIsMissing | Yes | The BuildRun related TaskRun was not found. | -| False | TaskRunGenerationFailed | Yes | The generation of a TaskRun spec failed. | -| False | MissingParameterValues | Yes | No value has been provided for some parameters that are defined in the build strategy without any default. Values for those parameters must be provided through the Build or the BuildRun. | -| False | RestrictedParametersInUse | Yes | A value for a system parameter was provided. This is not allowed. | -| False | UndefinedParameter | Yes | A value for a parameter was provided that is not defined in the build strategy. | -| False | WrongParameterValueType | Yes | A value was provided for a build strategy parameter using the wrong type. The parameter is defined as `array` or `string` in the build strategy. Depending on that, you must provide `values` or a direct value. | -| False | InconsistentParameterValues | Yes | A value for a parameter contained more than one of `value`, `configMapValue`, and `secretValue`. Any values including array items must only provide one of them. | -| False | EmptyArrayItemParameterValues | Yes | An item inside the `values` of an array parameter contained none of `value`, `configMapValue`, and `secretValue`. Exactly one of them must be provided. Null array items are not allowed. | -| False | IncompleteConfigMapValueParameterValues | Yes | A value for a parameter contained a `configMapValue` where the `name` or the `value` were empty. You must specify them to point to an existing ConfigMap key in your namespace. | -| False | IncompleteSecretValueParameterValues | Yes | A value for a parameter contained a `secretValue` where the `name` or the `value` were empty. You must specify them to point to an existing Secret key in your namespace. | -| False | ServiceAccountNotFound | Yes | The referenced service account was not found in the cluster. | -| False | BuildRegistrationFailed | Yes | The related Build in the BuildRun is in a Failed state. | -| False | BuildNotFound | Yes | The related Build in the BuildRun was not found. | -| False | BuildRunCanceled | Yes | The BuildRun and underlying TaskRun were canceled successfully. | -| False | BuildRunNameInvalid | Yes | The defined `BuildRun` name (`metadata.name`) is invalid. The `BuildRun` name should be a [valid label value](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). | -| False | BuildRunNoRefOrSpec | Yes | BuildRun does not have either `BuildRef` or `BuildSpec` defined. There is no connection to a Build specification. | -| False | BuildRunAmbiguousBuild | Yes | The defined `BuildRun` uses both `BuildRef` and `BuildSpec`. Only one of them is allowed at the same time.| -| False | BuildRunBuildFieldOverrideForbidden | Yes | The defined `BuildRun` uses an override (e.g. `timeout`, `paramValues`, `output`, or `env`) in combination with `BuildSpec`, which is not allowed. Use the `BuildSpec` to directly specify the respective value. | -| False | PodEvicted | Yes | The BuildRun Pod was evicted from the node it was running on. See [API-initiated Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/api-eviction/) and [Node-pressure Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/node-pressure-eviction/) for more information. | - -_Note_: We heavily rely on the Tekton TaskRun [Conditions](https://github.com/tektoncd/pipeline/blob/main/docs/taskruns.md#monitoring-execution-status) for populating the BuildRun ones, with some exceptions. +| Status | Reason | CompletionTime is set | Description | +|---------|-----------------------------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Unknown | Pending | No | The BuildRun is waiting on a Pod in status Pending. | +| Unknown | Running | No | The BuildRun has been validated and started to perform its work. | +| Unknown | Running | No | The BuildRun has been validated and started to perform its work. | +| Unknown | BuildRunCanceled | No | The user requested the BuildRun to be canceled. This results in the BuildRun controller requesting the TaskRun be canceled. Cancellation has not been done yet. | +| True | Succeeded | Yes | The BuildRun Pod is done. | +| False | Failed | Yes | The BuildRun failed in one of the steps. | +| False | BuildRunTimeout | Yes | The BuildRun timed out. | +| False | UnknownStrategyKind | Yes | The Build specified strategy Kind is unknown. (_options: ClusterBuildStrategy or BuildStrategy_) | +| False | ClusterBuildStrategyNotFound | Yes | The referenced cluster strategy was not found in the cluster. | +| False | BuildStrategyNotFound | Yes | The referenced namespaced strategy was not found in the cluster. | +| False | SetOwnerReferenceFailed | Yes | Setting ownerreferences from the BuildRun to the related TaskRun failed. | +| False | TaskRunIsMissing | Yes | The BuildRun related TaskRun was not found. | +| False | TaskRunGenerationFailed | Yes | The generation of a TaskRun spec failed. | +| False | MissingParameterValues | Yes | No value has been provided for some parameters that are defined in the build strategy without any default. Values for those parameters must be provided through the Build or the BuildRun. | +| False | RestrictedParametersInUse | Yes | A value for a system parameter was provided. This is not allowed. | +| False | UndefinedParameter | Yes | A value for a parameter was provided that is not defined in the build strategy. | +| False | WrongParameterValueType | Yes | A value was provided for a build strategy parameter using the wrong type. The parameter is defined as `array` or `string` in the build strategy. Depending on that, you must provide `values` or a direct value. | +| False | InconsistentParameterValues | Yes | A value for a parameter contained more than one of `value`, `configMapValue`, and `secretValue`. Any values including array items must only provide one of them. | +| False | EmptyArrayItemParameterValues | Yes | An item inside the `values` of an array parameter contained none of `value`, `configMapValue`, and `secretValue`. Exactly one of them must be provided. Null array items are not allowed. | +| False | IncompleteConfigMapValueParameterValues | Yes | A value for a parameter contained a `configMapValue` where the `name` or the `value` were empty. You must specify them to point to an existing ConfigMap key in your namespace. | +| False | IncompleteSecretValueParameterValues | Yes | A value for a parameter contained a `secretValue` where the `name` or the `value` were empty. You must specify them to point to an existing Secret key in your namespace. | +| False | ServiceAccountNotFound | Yes | The referenced service account was not found in the cluster. | +| False | BuildRegistrationFailed | Yes | The related Build in the BuildRun is in a Failed state. | +| False | BuildNotFound | Yes | The related Build in the BuildRun was not found. | +| False | BuildRunCanceled | Yes | The BuildRun and underlying TaskRun were canceled successfully. | +| False | BuildRunNameInvalid | Yes | The defined `BuildRun` name (`metadata.name`) is invalid. The `BuildRun` name should be a [valid label value](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). | +| False | BuildRunNoRefOrSpec | Yes | BuildRun does not have either `spec.build.name` or `spec.build.spec` defined. There is no connection to a Build specification. | +| False | BuildRunAmbiguousBuild | Yes | The defined `BuildRun` uses both `spec.build.name` and `spec.build.spec`. Only one of them is allowed at the same time. | +| False | BuildRunBuildFieldOverrideForbidden | Yes | The defined `BuildRun` uses an override (e.g. `timeout`, `paramValues`, `output`, or `env`) in combination with `spec.build.spec`, which is not allowed. Use the `spec.build.spec` to directly specify the respective value. | +| False | PodEvicted | Yes | The BuildRun Pod was evicted from the node it was running on. See [API-initiated Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/api-eviction/) and [Node-pressure Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/node-pressure-eviction/) for more information. | + +**Note**: We heavily rely on the Tekton TaskRun [Conditions](https://github.com/tektoncd/pipeline/blob/main/docs/taskruns.md#monitoring-execution-status) for populating the BuildRun ones, with some exceptions. ### Understanding failed BuildRuns -[DEPRECATED] To make it easier for users to understand why did a BuildRun failed, users can infer the pod and container where the failure took place from the `status.failedAt` field. +To make it easier for users to understand why did a BuildRun failed, users can infer the pod and container where the failure took place from the `status.failureDetails` field. -In addition, the `status.conditions` hosts a compacted message under the' message' field that contains the `kubectl` command to trigger and retrieve the logs. +In addition, the `status.conditions` hosts a compacted message under the `message` field that contains the `kubectl` command to trigger and retrieve the logs. -Lastly, users can check the `status.failureDetails` field, which includes the same information available in the `status.failedAt` field, -as well as a human-readable error message and reason. -The message and reason are only included if the build strategy provides them. +The `status.failureDetails` field also includes a detailed failure reason and message, if the build strategy provides them. Example of failed BuildRun: @@ -410,17 +425,17 @@ status: All git-related operations support error reporting via `status.failureDetails`. The following table explains the possible error reasons: -| Reason | Description | -| --- | --- | -| `GitAuthInvalidUserOrPass` | Basic authentication has failed. Check your username or password. Note: GitHub requires a personal access token instead of your regular password. | -| `GitAuthInvalidKey` | The key is invalid for the specified target. Please make sure that the Git repository exists, you have sufficient permissions, and the key is in the right format. | -| `GitRevisionNotFound` | The remote revision does not exist. Check the revision specified in your Build. | -| `GitRemoteRepositoryNotFound`| The source repository does not exist, or you have insufficient permissions to access it. | -| `GitRemoteRepositoryPrivate` | You are trying to access a non-existing or private repository without having sufficient permissions to access it via HTTPS. | -| `GitBasicAuthIncomplete`| Basic Auth incomplete: Both username and password must be configured. | -| `GitSSHAuthUnexpected`| Credential/URL inconsistency: SSH credentials were provided, but the URL is not an SSH Git URL. | -| `GitSSHAuthExpected`| Credential/URL inconsistency: No SSH credentials provided, but the URL is an SSH Git URL. | -| `GitError` | The specific error reason is unknown. Check the error message for more information. | +| Reason | Description | +|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `GitAuthInvalidUserOrPass` | Basic authentication has failed. Check your username or password. **Note**: GitHub requires a personal access token instead of your regular password. | +| `GitAuthInvalidKey` | The key is invalid for the specified target. Please make sure that the Git repository exists, you have sufficient permissions, and the key is in the right format. | +| `GitRevisionNotFound` | The remote revision does not exist. Check the revision specified in your Build. | +| `GitRemoteRepositoryNotFound` | The source repository does not exist, or you have insufficient permissions to access it. | +| `GitRemoteRepositoryPrivate` | You are trying to access a non-existing or private repository without having sufficient permissions to access it via HTTPS. | +| `GitBasicAuthIncomplete` | Basic Auth incomplete: Both username and password must be configured. | +| `GitSSHAuthUnexpected` | Credential/URL inconsistency: SSH credentials were provided, but the URL is not an SSH Git URL. | +| `GitSSHAuthExpected` | Credential/URL inconsistency: No SSH credentials provided, but the URL is an SSH Git URL. | +| `GitError` | The specific error reason is unknown. Check the error message for more information. | ### Step Results in BuildRun Status @@ -446,7 +461,7 @@ status: branchName: main ``` -Another example of a `BuildRun` with surfaced results for local source code(`bundle`) source: +Another example of a `BuildRun` with surfaced results for local source code(`ociArtifact`) source: ```yaml # [...] @@ -458,7 +473,7 @@ status: size: 1989004 sources: - name: default - bundle: + ociArtifact: digest: sha256:0f5e2070b534f9b880ed093a537626e3c7fdd28d5328a8d6df8d29cd3da760c7 ``` diff --git a/content/en/docs/build/buildstrategies.md b/content/en/docs/build/buildstrategies.md index 4e388a2a..c1f14b34 100644 --- a/content/en/docs/build/buildstrategies.md +++ b/content/en/docs/build/buildstrategies.md @@ -28,14 +28,17 @@ SPDX-License-Identifier: Apache-2.0 - [ko](#ko) - [Installing ko Strategy](#installing-ko-strategy) - [Parameters](#parameters) + - [Volumes](#volumes) - [Source to Image](#source-to-image) - [Installing Source to Image Strategy](#installing-source-to-image-strategy) - [Build Steps](#build-steps) - [Strategy parameters](#strategy-parameters) - [System parameters](#system-parameters) + - [Output directory vs. output image](#output-directory-vs-output-image) - [System parameters vs Strategy Parameters Comparison](#system-parameters-vs-strategy-parameters-comparison) - [Securely referencing string parameters](#securely-referencing-string-parameters) - [System results](#system-results) +- [Security Contexts](#security-contexts) - [Steps Resource Definition](#steps-resource-definition) - [Strategies with different resources](#strategies-with-different-resources) - [How does Tekton Pipelines handle resources](#how-does-tekton-pipelines-handle-resources) @@ -45,23 +48,23 @@ SPDX-License-Identifier: Apache-2.0 ## Overview -There are two types of strategies, the `ClusterBuildStrategy` (`clusterbuildstrategies.shipwright.io/v1alpha1`) and the `BuildStrategy` (`buildstrategies.shipwright.io/v1alpha1`). Both strategies define a shared group of steps, needed to fullfil the application build. +There are two types of strategies, the `ClusterBuildStrategy` (`clusterbuildstrategies.shipwright.io/v1beta1`) and the `BuildStrategy` (`buildstrategies.shipwright.io/v1beta1`). Both strategies define a shared group of steps, needed to fullfil the application build. A `ClusterBuildStrategy` is available cluster-wide, while a `BuildStrategy` is available within a namespace. ## Available ClusterBuildStrategies -Well-known strategies can be bootstrapped from [here](../samples/buildstrategy). The currently supported Cluster BuildStrategy are: +Well-known strategies can be bootstrapped from [here](../samples/v1beta1/buildstrategy). The currently supported Cluster BuildStrategy are: | Name | Supported platforms | | ---- | ------------------- | -| [buildah](../samples/buildstrategy/buildah/buildstrategy_buildah_cr.yaml) | all | -| [BuildKit](../samples/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml) | all | -| [buildpacks-v3-heroku](../samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_cr.yaml) | linux/amd64 only | -| [buildpacks-v3](../samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_cr.yaml) | linux/amd64 only | -| [kaniko](../samples/buildstrategy/kaniko/buildstrategy_kaniko_cr.yaml) | all | -| [ko](../samples/buildstrategy/ko/buildstrategy_ko_cr.yaml) | all | -| [source-to-image](../samples/buildstrategy/source-to-image/buildstrategy_source-to-image_cr.yaml) | linux/amd64 only | +| [buildah](../samples/v1beta1/buildstrategy/buildah) | all | +| [BuildKit](../samples/v1beta1/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml) | all | +| [buildpacks-v3-heroku](../samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_cr.yaml) | linux/amd64 only | +| [buildpacks-v3](../samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_cr.yaml) | linux/amd64 only | +| [kaniko](../samples/v1beta1/buildstrategy/kaniko/buildstrategy_kaniko_cr.yaml) | all | +| [ko](../samples/v1beta1/buildstrategy/ko/buildstrategy_ko_cr.yaml) | all | +| [source-to-image](../samples/v1beta1/buildstrategy/source-to-image/buildstrategy_source-to-image_cr.yaml) | linux/amd64 only | ## Available BuildStrategies @@ -69,47 +72,59 @@ The current supported namespaces BuildStrategy are: | Name | Supported platforms | | ---- | ------------------- | -| [buildpacks-v3-heroku](../samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_namespaced_cr.yaml) | linux/amd64 only | -| [buildpacks-v3](../samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_namespaced_cr.yaml) | linux/amd64 only | +| [buildpacks-v3-heroku](../samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_namespaced_cr.yaml) | linux/amd64 only | +| [buildpacks-v3](../samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_namespaced_cr.yaml) | linux/amd64 only | --- ## Buildah -The `buildah` ClusterBuildStrategy consists of using [`buildah`](https://github.com/containers/buildah) to build and push a container image, out of a `Dockerfile`. The `Dockerfile` should be specified on the `Build` resource. +The `buildah` ClusterBuildStrategy uses [`buildah`](https://github.com/containers/buildah) to build and push a container image, out of a `Dockerfile`. The `Dockerfile` should be specified on the `Build` resource. + +The strategy is available in two formats: + +- [`buildah-shipwright-managed-push`](../samples/v1beta1/buildstrategy/buildah/buildstrategy_buildah_shipwright_managed_push%20copy_cr.yaml) +- [`buildah-strategy-managed-push`](../samples/v1beta1/buildstrategy/buildah/buildstrategy_buildah_strategy_managed_push_cr.yaml) + +Learn more about the differences of [shipwright-, or strategy-managed push](#output-directory-vs-output-image) ### Installing Buildah Strategy To install use: ```sh -kubectl apply -f samples/buildstrategy/buildah/buildstrategy_buildah_cr.yaml +kubectl apply -f samples/v1beta1/buildstrategy/buildah/buildstrategy_buildah_shipwright_managed_push_cr.yaml +kubectl apply -f samples/v1beta1/buildstrategy/buildah/buildstrategy_buildah_strategy_managed_push_cr.yaml ``` --- ## Buildpacks v3 -The [buildpacks-v3][buildpacks] BuildStrategy/ClusterBuildStrategy uses a Cloud Native Builder ([CNB][cnb]) container image, and is able to implement [lifecycle commands][lifecycle]. The following CNB images are the most common options: - -- [`heroku/buildpacks:18`][hubheroku] -- [`cloudfoundry/cnb:bionic`][hubcloudfoundry] -- [`docker.io/paketobuildpacks/builder:full`](https://hub.docker.com/r/paketobuildpacks/builder/tags) +The [buildpacks-v3][buildpacks] BuildStrategy/ClusterBuildStrategy uses a Cloud Native Builder ([CNB][cnb]) container image, and is able to implement [lifecycle commands][lifecycle]. ### Installing Buildpacks v3 Strategy You can install the `BuildStrategy` in your namespace or install the `ClusterBuildStrategy` at cluster scope so that it can be shared across namespaces. -To install the cluster scope strategy, use (below is a heroku example, you can also use paketo sample): +To install the cluster scope strategy, you can chose between the Paketo and Heroku buildpacks family: ```sh -kubectl apply -f samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_cr.yaml +# Paketo +kubectl apply -f samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_cr.yaml + +# Heroku +kubectl apply -f samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_cr.yaml ``` -To install the namespaced scope strategy, use: +To install the namespaced scope strategy, you can chose between the Paketo and Heroku buildpacks family: ```sh -kubectl apply -f samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_namespaced_cr.yaml +# Paketo +kubectl apply -f samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_namespaced_cr.yaml + +# Heroku +kubectl apply -f samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3-heroku_namespaced_cr.yaml ``` --- @@ -123,7 +138,7 @@ The `kaniko` ClusterBuildStrategy is composed by Kaniko's `executor` [kaniko], w To install the cluster scope strategy, use: ```sh -kubectl apply -f samples/buildstrategy/kaniko/buildstrategy_kaniko_cr.yaml +kubectl apply -f samples/v1beta1/buildstrategy/kaniko/buildstrategy_kaniko_cr.yaml ``` #### Scanning with Trivy @@ -133,7 +148,7 @@ You can also incorporate scanning into the ClusterBuildStrategy. The `kaniko-tri To install the cluster scope strategy, use: ```sh -kubectl apply -f samples/buildstrategy/kaniko/buildstrategy_kaniko-trivy_cr.yaml +kubectl apply -f samples/v1beta1/buildstrategy/kaniko/buildstrategy_kaniko-trivy_cr.yaml ``` *Note: doing image scanning is not a substitute for trusting the Dockerfile you are building. The build process itself is also susceptible if the Dockerfile has a vulnerability. Frameworks/strategies such as build-packs or source-to-image (which avoid directly building a Dockerfile) should be considered if you need guardrails around the code you want to build.* @@ -179,21 +194,21 @@ _Please note:_ At this point in time, there is no way to run `rootlesskit` to st To install the cluster scope strategy, use: ```sh -kubectl apply -f samples/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml +kubectl apply -f samples/v1beta1/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml ``` --- ## ko -The `ko` ClusterBuilderStrategy is using [ko](https://github.com/google/ko)'s publish command to build an image from a Golang main package. +The `ko` ClusterBuilderStrategy is using [ko](https://github.com/ko-build/ko)'s publish command to build an image from a Golang main package. ### Installing ko Strategy To install the cluster scope strategy, use: ```sh -kubectl apply -f samples/buildstrategy/ko/buildstrategy_ko_cr.yaml +kubectl apply -f samples/v1beta1/buildstrategy/ko/buildstrategy_ko_cr.yaml ``` ### Parameters @@ -203,8 +218,8 @@ The build strategy provides the following parameters that you can set in a Build | Parameter | Description | Default | | -- | -- | -- | | `go-flags` | Value for the GOFLAGS environment variable. | Empty | -| `go-version` | Version of Go, must match a tag from [the golang image](https://hub.docker.com/_/golang?tab=tags) | `1.18` | -| `ko-version` | Version of ko, must be either `latest` for the newest release, or a [ko release name](https://github.com/google/ko/releases) | `latest` | +| `go-version` | Version of Go, must match a tag from [the golang image](https://hub.docker.com/_/golang?tab=tags) | `1.21` | +| `ko-version` | Version of ko, must be either `latest` for the newest release, or a [ko release name](https://github.com/ko-build/ko/releases) | `latest` | | `package-directory` | The directory inside the context directory containing the main package. | `.` | | `target-platform` | Target platform to be built. For example: `linux/arm64`. Multiple platforms can be provided separated by comma, for example: `linux/arm64,linux/amd64`. The value `all` will build all platforms supported by the base image. The value `current` will build the platform on which the build runs. | `current` | @@ -225,7 +240,7 @@ This BuildStrategy is composed by [`source-to-image`][s2i] and [`kaniko`][kaniko To install the cluster scope strategy use: ```sh -kubectl apply -f samples/buildstrategy/source-to-image/buildstrategy_source-to-image_cr.yaml +kubectl apply -f samples/v1beta1/buildstrategy/source-to-image/buildstrategy_source-to-image_cr.yaml ``` ### Build Steps @@ -250,7 +265,7 @@ Users defining _parameters_ under their strategies require to understand the fol - **Definition**: A list of parameters should be defined under `spec.parameters`. Each list item should consist of a _name_, a _description_, a _type_ (either `"array"` or `"string"`) and optionally a _default_ value (for type=string), or _defaults_ values (for type=array). If no default(s) are provided, then the user must define a value in the Build or BuildRun. - **Usage**: In order to use a parameter in the strategy steps, use the following syntax for type=string: `$(params.your-parameter-name)`. String parameters can be used in all places in the `buildSteps`. Some example scenarios are: - - `image`: to use a custom tag, for example `golang:$(params.go-version)` as it is done in the [ko sample build strategy](../samples/buildstrategy/ko/buildstrategy_ko_cr.yaml)) + - `image`: to use a custom tag, for example `golang:$(params.go-version)` as it is done in the [ko sample build strategy](../samples/v1beta1/buildstrategy/ko/buildstrategy_ko_cr.yaml)) - `args`: to pass data into your builder command - `env`: to force a user to provide a value for an environment variable. @@ -262,7 +277,7 @@ Users defining _parameters_ under their strategies require to understand the fol - name: tool-args description: Parameters for the tool type: array - buildSteps: + steps: - name: a-step command: - some-tool @@ -286,11 +301,11 @@ Users defining _parameters_ under their strategies require to understand the fol **Note**: Users can provide parameter values as simple strings or as references to keys in [ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/) and [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/). If they use a ConfigMap or Secret, then the value can only be used if the parameter is used in the `command`, `args`, or `env` section of the `buildSteps`. For example, the above mentioned scenario to set a step's `image` to `golang:$(params.go-version)` does not allow the usage of ConfigMaps or Secrets. -The following example is from the [BuildKit sample build strategy](../samples/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml). It defines and uses several parameters: +The following example is from the [BuildKit sample build strategy](../samples/v1beta1/buildstrategy/buildkit/buildstrategy_buildkit_cr.yaml). It defines and uses several parameters: ```yaml --- -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: buildkit @@ -313,7 +328,11 @@ spec: description: "The secrets to pass to the build. Values must be in the format ID=FILE_CONTENT." type: array defaults: [] - buildSteps: + - name: dockerfile + description: The path to the Dockerfile to be used for building the image. + type: string + default: "Dockerfile" + steps: ... - name: build-and-push image: moby/buildkit:nightly-rootless @@ -328,7 +347,7 @@ spec: set -euo pipefail # Prepare the file arguments - DOCKERFILE_PATH='$(params.shp-source-context)/$(build.dockerfile)' + DOCKERFILE_PATH='$(params.shp-source-context)/$(params.dockerfile)' DOCKERFILE_DIR="$(dirname "${DOCKERFILE_PATH}")" DOCKERFILE_NAME="$(basename "${DOCKERFILE_PATH}")" @@ -412,7 +431,27 @@ Contrary to the strategy `spec.parameters`, you can use system parameters and th | ------------------------------ | ----------- | | `$(params.shp-source-root)` | The absolute path to the directory that contains the user's sources. | | `$(params.shp-source-context)` | The absolute path to the context directory of the user's sources. If the user specified no value for `spec.source.contextDir` in their `Build`, then this value will equal the value for `$(params.shp-source-root)`. Note that this directory is not guaranteed to exist at the time the container for your step is started, you can therefore not use this parameter as a step's working directory. | -| `$(params.shp-output-image)` | The URL of the image that the user wants to push as specified in the Build's `spec.output.image`, or the override from the BuildRun's `spec.output.image`. | +| `$(params.shp-output-directory)` | The absolute path to a directory that the build strategy should store the image in. You can store a single tarball containing a single image, or an OCI image layout. | +| `$(params.shp-output-image)` | The URL of the image that the user wants to push, as specified in the Build's `spec.output.image` or as an override from the BuildRun's `spec.output.image`. | +| `$(params.shp-output-insecure)` | A flag that indicates the output image's registry location is insecure because it uses a certificate not signed by a certificate authority, or uses HTTP. | + +### Output directory vs. output image + +As a build strategy author, you decide whether your build strategy or Shipwright pushes the build image to the container registry: + +- If you DO NOT use `$(params.shp-output-directory)`, then Shipwright assumes that your build strategy PUSHES the image. We call this a strategy-managed push. +- If you DO use `$(params.shp-output-directory)`, then Shipwright assumes that your build strategy does NOT PUSH the image. We call this a shipwright-managed push. + +When you use the `$(params.shp-output-directory)` parameter, then Shipwright will also set the [image-related system results](#system-results). + +If you are uncertain about how to implement your build strategy, then follow this guidance: + +1. If your build strategy tool cannot locally store an image but always pushes it, then you must do the push operation. An example is the [Buildpacks strategy](../samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_cr.yaml). You SHOULD respect the `$(params.shp-output-insecure)` parameter. +2. If your build strategy tool can locally store an image, then the choice depends on how you expect your build users to make use of your strategy, and the nature of your strategy. + 1. Some build strategies do not produce all layers of an image, but use a common base image and put one or more layers on top with the application. An example is `ko`. Such base image layers are often already present in the destination registry (like in rebuilds). If the strategy can perform the push operation, then it can optimize the process and can omit the download of the base image when it is not required to push it. In the case of a shipwright-managed push, the complete image must be locally stored in `$(params.shp-output-directory)`, which implies that a base image must always be downloaded. + 2. Some build strategy tools do not make it easy to determine the digest or size of the image, which can make it complex for your to set the [strategy results](#system-results). In the case of a shipwright-managed push, Shipwright has the responsibility to set them. + 3. Build users can configure the build to amend additional annotations, or labels to the final image. In the case of a shipwright-managed push, these can be set directly and the image will only be pushed once. In a strategy-managed push scenario, your build strategy will push the first version of the image without those annotations and labels. Shipwright will then mutate the image and push it again with the updated annotations and labels. Such a duplicate push can cause unexpected behavior with registries that trigger other actions when an image gets pushed, or that do not allow overwriting a tag. + 4. The Shipwright maintainers plan to provide more capabilities in the future that need the image locally, such as vulnerability scanning, or software bill of material (SBOM) creation. These capabilities may be only fully supported with shipwright-managed push. ## System parameters vs Strategy Parameters Comparison @@ -431,7 +470,7 @@ spec: - name: sample-parameter description: A sample parameter type: string - buildSteps: + steps: - name: sample-step command: - /bin/bash @@ -454,7 +493,7 @@ This opens the door to script injection, for example if the user sets the `sampl To securely pass a parameter value into a script-style argument, you can chose between these two approaches: -1. Using environment variables. This is used in some of our sample strategies, for example [ko](../samples/buildstrategy/ko/buildstrategy_ko_cr.yaml), or [buildpacks](../samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_cr.yaml). Basically, instead of directly using the parameter inside the script, you pass it via environment variable. Using quoting, shells ensure that no command injection is possible: +1. Using environment variables. This is used in some of our sample strategies, for example [ko](../samples/v1beta1/buildstrategy/ko/buildstrategy_ko_cr.yaml), or [buildpacks](../samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_cr.yaml). Basically, instead of directly using the parameter inside the script, you pass it via environment variable. Using quoting, shells ensure that no command injection is possible: ```yaml spec: @@ -462,7 +501,7 @@ To securely pass a parameter value into a script-style argument, you can chose b - name: sample-parameter description: A sample parameter type: string - buildSteps: + steps: - name: sample-step env: - name: PARAM_SAMPLE_PARAMETER @@ -477,7 +516,7 @@ To securely pass a parameter value into a script-style argument, you can chose b some-tool --sample-argument "${PARAM_SAMPLE_PARAMETER}" ``` -2. Using arguments. This is used in some of our sample build strategies, for example [buildah](../samples/buildstrategy/buildah/buildstrategy_buildah_cr.yaml). Here, you use arguments to your own inline script. Appropriate shell quoting guards against command injection. +2. Using arguments. This is used in some of our sample build strategies, for example [buildah](../samples/v1beta1/buildstrategy/buildah/buildstrategy_buildah_cr.yaml). Here, you use arguments to your own inline script. Appropriate shell quoting guards against command injection. ```yaml spec: @@ -485,7 +524,7 @@ To securely pass a parameter value into a script-style argument, you can chose b - name: sample-parameter description: A sample parameter type: string - buildSteps: + steps: - name: sample-step command: - /bin/bash @@ -503,19 +542,19 @@ To securely pass a parameter value into a script-style argument, you can chose b ## System results -You can optionally store the size and digest of the image your build strategy created to a set of files. +If you are using a strategy-managed push, see [output directory vs output image](#output-directory-vs-output-image), you can optionally store the size and digest of the image your build strategy created to a set of files. | Result file | Description | | ---------------------------------- | ----------------------------------------------- | | `$(results.shp-image-digest.path)` | File to store the digest of the image. | | `$(results.shp-image-size.path)` | File to store the compressed size of the image. | -You can look at sample build strategies, such as [Kaniko](../samples/buildstrategy/kaniko/buildstrategy_kaniko_cr.yaml), or [Buildpacks](../samples/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_cr.yaml), to see how they fill some or all of the results files. +You can look at sample build strategies, such as [Buildpacks](../samples/v1beta1/buildstrategy/buildpacks-v3/buildstrategy_buildpacks-v3_cr.yaml), to see how they fill some or all of the results files. -This information will be available in the `.status.output` field of the BuildRun. +This information will be available in the `.status.output` section of the BuildRun. ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun # [...] status: @@ -535,10 +574,10 @@ Additionally, you can store error details for debugging purposes when a BuildRun Reason is intended to be a one-word CamelCase classification of the error source, with the first letter capitalized. Error details are only propagated if the build container terminates with a non-zero exit code. -This information will be available in the `.status.failureDetails` field of the BuildRun. +This information will be available in the `.status.failureDetails` section of the BuildRun. ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildRun # [...] status: @@ -552,6 +591,23 @@ status: reason: GitRemotePrivate ``` +## Security Contexts + +In a build strategy, it is recommended that you define a `securityContext` with a runAsUser and runAsGroup: + +```yaml +spec: + securityContext: + runAsUser: 1000 + runAsGroup: 1000 +``` + +This runAs configuration will be used for all shipwright-managed steps such as the step that retrieves the source code, and for the steps you define in the build strategy. This configuration ensures that all steps share the same runAs configuration which eliminates file permission problems. + +Without a `securityContext` for the build strategy, shipwright-managed steps will run with the `runAsUser` and `runAsGroup` that is defined in the [configuration's container templates](configuration.md) that is potentially a different user than you use in your build strategy. This can result in issues when for example source code is downloaded as user A as defined by the Git container template, but your strategy accesses it as user B. + +In build strategy steps you can define a step-specific `securityContext` that matches [Kubernetes' security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) where you can configure other security aspects such as capabilities or privileged containers. + ## Steps Resource Definition All strategies steps can include a definition of resources(_limits and requests_) for CPU, memory and disk. For strategies with more than one step, each step(_container_) could require more resources than others. Strategy admins are free to define the values that they consider the best fit for each step. Also, identical strategies with the same steps that are only different in their name and step resources can be installed on the cluster to allow users to create a build with smaller and larger resource requirements. @@ -562,14 +618,14 @@ If the strategy admins would require to have multiple flavours of the same strat ```yaml --- -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: kaniko-small spec: - buildSteps: + steps: - name: build-and-push - image: gcr.io/kaniko-project/executor:v1.8.1 + image: gcr.io/kaniko-project/executor:v1.21.1 workingDir: $(params.shp-source-root) securityContext: runAsUser: 0 @@ -593,10 +649,10 @@ spec: - /kaniko/executor args: - --skip-tls-verify=true - - --dockerfile=$(build.dockerfile) + - --dockerfile=$(params.dockerfile) - --context=$(params.shp-source-context) - --destination=$(params.shp-output-image) - - --snapshotMode=redo + - --snapshot-mode=redo - --push-retry=3 resources: limits: @@ -605,15 +661,20 @@ spec: requests: cpu: 250m memory: 65Mi + parameters: + - name: dockerfile + description: The path to the Dockerfile to be used for building the image. + type: string + default: "Dockerfile" --- -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: kaniko-medium spec: - buildSteps: + steps: - name: build-and-push - image: gcr.io/kaniko-project/executor:v1.8.1 + image: gcr.io/kaniko-project/executor:v1.21.1 workingDir: $(params.shp-source-root) securityContext: runAsUser: 0 @@ -637,10 +698,10 @@ spec: - /kaniko/executor args: - --skip-tls-verify=true - - --dockerfile=$(build.dockerfile) + - --dockerfile=$(params.dockerfile) - --context=$(params.shp-source-context) - --destination=$(params.shp-output-image) - - --snapshotMode=redo + - --snapshot-mode=redo - --push-retry=3 resources: limits: @@ -649,24 +710,32 @@ spec: requests: cpu: 500m memory: 1Gi + parameters: + - name: dockerfile + description: The path to the Dockerfile to be used for building the image. + type: string + default: "Dockerfile" ``` The above provides more control and flexibility for the strategy admins. For `end-users`, all they need to do, is to reference the proper strategy. For example: ```yaml --- -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: kaniko-medium spec: source: - url: https://github.com/shipwright-io/sample-go + git: + url: https://github.com/shipwright-io/sample-go contextDir: docker-build strategy: name: kaniko kind: ClusterBuildStrategy - dockerfile: Dockerfile + paramValues: + - name: dockerfile + value: Dockerfile ``` ### How does Tekton Pipelines handle resources @@ -689,11 +758,11 @@ If we will apply the following resources: - [buildahBuild](../samples/build/build_buildah_cr.yaml) - [buildahBuildRun](../samples/buildrun/buildrun_buildah_cr.yaml) -- [buildahClusterBuildStrategy](../samples/buildstrategy/buildah/buildstrategy_buildah_cr.yaml) +- [buildahClusterBuildStrategy](../samples/v1beta1/buildstrategy/buildah/buildstrategy_buildah_cr.yaml) We will see some differences between the `TaskRun` definition and the `pod` definition. -For the `TaskRun`, as expected we can see the resources on each `step`, as we previously define on our [strategy](../samples/buildstrategy/buildah/buildstrategy_buildah_cr.yaml). +For the `TaskRun`, as expected we can see the resources on each `step`, as we previously define on our [strategy](../samples/v1beta1/buildstrategy/buildah/buildstrategy_buildah_cr.yaml). ```sh $ kubectl -n test-build get tr buildah-golang-buildrun-9gmcx-pod-lhzbc -o json | jq '.spec.taskSpec.steps[] | select(.name == "step-buildah-bud" ) | .resources' @@ -765,7 +834,7 @@ If we will apply the following resources: ```yaml - name: buildah-bud - image: quay.io/containers/buildah:v1.20.1 + image: quay.io/containers/buildah:v1.34.0 workingDir: $(params.shp-source-root) securityContext: privileged: true @@ -774,7 +843,7 @@ If we will apply the following resources: args: - bud - --tag=$(params.shp-output-image) - - --file=$(build.dockerfile) + - --file=$(params.dockerfile) - $(build.source.contextDir) resources: limits: @@ -787,7 +856,7 @@ If we will apply the following resources: - name: buildah-images mountPath: /var/lib/containers/storage - name: buildah-push - image: quay.io/containers/buildah:v1.20.1 + image: quay.io/containers/buildah:v1.34.0 securityContext: privileged: true command: @@ -901,14 +970,14 @@ Build steps can declare a `volumeMount`, which allows them to access volumes def Here is an example of `BuildStrategy` object that defines `volumes` and `volumeMount`s: ``` -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: BuildStrategy metadata: name: buildah spec: - buildSteps: + steps: - name: build - image: quay.io/containers/buildah:v1.23.3 + image: quay.io/containers/buildah:v1.27.0 workingDir: $(params.shp-source-root) command: - buildah @@ -916,7 +985,7 @@ spec: - --tls-verify=false - --layers - -f - - $(build.dockerfile) + - $(params.dockerfile) - -t - $(params.shp-output-image) - $(params.shp-source-context) @@ -927,4 +996,5 @@ spec: - name: varlibcontainers overridable: true emptyDir: {} + # ... ``` diff --git a/content/en/docs/build/configuration.md b/content/en/docs/build/configuration.md index 8d2ae5e1..c03c8b73 100644 --- a/content/en/docs/build/configuration.md +++ b/content/en/docs/build/configuration.md @@ -2,39 +2,43 @@ title: "Configuration" draft: false --- - - ## Controller Settings -The controller is installed into Kubernetes with reasonable defaults. However, there are some settings that can be overridden using environment variables in [`controller.yaml`](https://github.com/shipwright-io/build/blob/v0.10.0/deploy/500-controller.yaml). +The controller is installed into Kubernetes with reasonable defaults. However, there are some settings that can be overridden using environment variables in [`controller.yaml`](../deploy/500-controller.yaml). The following environment variables are available: | Environment Variable | Description | | --- | --- | -| `CTX_TIMEOUT` | Override the default context timeout used for all Custom Resource Definition reconciliation operations. | -| `REMOTE_ARTIFACTS_CONTAINER_IMAGE` | Specify the container image used for the `.spec.sources` remote artifacts download, by default it uses `busybox:latest`. | -| `GIT_CONTAINER_TEMPLATE` | JSON representation of a [Container](https://pkg.go.dev/k8s.io/api/core/v1#Container) template that is used for steps that clone a Git repository. Default is `{"image":"ghcr.io/shipwright-io/build/git:latest", "command":["/ko-app/git"], "securityContext":{"runAsUser":1000,"runAsGroup":1000}}`. The following properties are ignored as they are set by the controller: `args`, `name`. | +| `CTX_TIMEOUT` | Override the default context timeout used for all Custom Resource Definition reconciliation operations. Default is 5 (seconds). | +| `REMOTE_ARTIFACTS_CONTAINER_IMAGE` | Specify the container image used for the `.spec.sources` remote artifacts download, by default it uses `quay.io/quay/busybox:latest`. | +| `TERMINATION_LOG_PATH` | Path of the termination log. This is where controller application will write the reason of its termination. Default value is `/dev/termination-log`. | +| `GIT_ENABLE_REWRITE_RULE` | Enable Git wrapper to setup a URL `insteadOf` Git config rewrite rule for the respective source URL hostname. Default is `false`. | +| `GIT_CONTAINER_TEMPLATE` | JSON representation of a [Container] template that is used for steps that clone a Git repository. Default is `{"image": "ghcr.io/shipwright-io/build/git:latest", "command": ["/ko-app/git"], "env": [{"name": "HOME", "value": "/shared-home"}], "securityContext":{"allowPrivilegeEscalation": false, "capabilities": {"drop": ["ALL"]}, "runAsUser": 1000,"runAsGroup": 1000}}` [^1]. The following properties are ignored as they are set by the controller: `args`, `name`. | | `GIT_CONTAINER_IMAGE` | Custom container image for Git clone steps. If `GIT_CONTAINER_TEMPLATE` is also specifying an image, then the value for `GIT_CONTAINER_IMAGE` has precedence. | -| `MUTATE_IMAGE_CONTAINER_TEMPLATE` | JSON representation of a [Container](https://pkg.go.dev/k8s.io/api/core/v1#Container) template that is used for steps that mutates an image if a `Build` has annotations or labels defined in the output. Default is `{"image": "ghcr.io/shipwright-io/build/mutate-image:latest", "command": ["/ko-app/mutate-image"], "env": [{"name": "HOME","value": "/tekton/home"}], "securityContext": {"runAsUser": 0, "capabilities": {"add": ["DAC_OVERRIDE"]}}}`. The following properties are ignored as they are set by the controller: `args`, `name`. | -| `MUTATE_IMAGE_CONTAINER_IMAGE` | Custom container image that is used for steps that mutates an image if a `Build` has annotations or labels defined in the output. If `MUTATE_IMAGE_CONTAINER_TEMPLATE` is also specifying an image, then the value for `MUTATE_IMAGE_CONTAINER_IMAGE` has precedence. | +| `BUNDLE_IMAGE_CONTAINER_TEMPLATE` | JSON representation of a [Container] template that is used for steps that pulls a bundle image to obtain the packaged source code. Default is `{"image": "ghcr.io/shipwright-io/build/bundle:latest", "command": ["/ko-app/bundle"], "env": [{"name": "HOME","value": "/shared-home"}], "securityContext":{"allowPrivilegeEscalation": false, "capabilities": {"drop": ["ALL"]}, "runAsUser":1000,"runAsGroup":1000}}` [^1]. The following properties are ignored as they are set by the controller: `args`, `name`. | +| `BUNDLE_IMAGE_CONTAINER_IMAGE` | Custom container image that pulls a bundle image to obtain the packaged source code. If `BUNDLE_IMAGE_CONTAINER_TEMPLATE` is also specifying an image, then the value for `BUNDLE_IMAGE_CONTAINER_IMAGE` has precedence. | +| `IMAGE_PROCESSING_CONTAINER_TEMPLATE` | JSON representation of a [Container](https://pkg.go.dev/k8s.io/api/core/v1#Container) template that is used for steps that processes the image. Default is `{"image": "ghcr.io/shipwright-io/build/image-processing:latest", "command": ["/ko-app/image-processing"], "env": [{"name": "HOME","value": "/shared-home"}], "securityContext": {"allowPrivilegeEscalation": false, "capabilities": {"add": ["DAC_OVERRIDE"], "drop": ["ALL"]}, "runAsUser": 0, "runAsgGroup": 0}}`. The following properties are ignored as they are set by the controller: `args`, `name`. | +| `IMAGE_PROCESSING_CONTAINER_IMAGE` | Custom container image that is used for steps that processes the image. If `IMAGE_PROCESSING_CONTAINER_TEMPLATE` is also specifying an image, then the value for `IMAGE_PROCESSING_CONTAINER_IMAGE` has precedence. | +| `WAITER_IMAGE_CONTAINER_TEMPLATE` | JSON representation of a [Container] template that waits for local source code to be uploaded to it. Default is `{"image":"ghcr.io/shipwright-io/build/waiter:latest", "command": ["/ko-app/waiter"], "args": ["start"], "env": [{"name": "HOME","value": "/shared-home"}], "securityContext":{"allowPrivilegeEscalation": false, "capabilities": {"drop": ["ALL"]}, "runAsUser":1000,"runAsGroup":1000}}`. The following properties are ignored as they are set by the controller: `args`, `name`. | +| `WAITER_IMAGE_CONTAINER_IMAGE` | Custom container image that waits for local source code to be uploaded to it. If `WAITER_IMAGE_CONTAINER_TEMPLATE` is also specifying an image, then the value for `WAITER_IMAGE_CONTAINER_IMAGE` has precedence. | | `BUILD_CONTROLLER_LEADER_ELECTION_NAMESPACE` | Set the namespace to be used to store the `shipwright-build-controller` lock, by default it is in the same namespace as the controller itself. | | `BUILD_CONTROLLER_LEASE_DURATION` | Override the `LeaseDuration`, which is the duration that non-leader candidates will wait to force acquire leadership. | | `BUILD_CONTROLLER_RENEW_DEADLINE` | Override the `RenewDeadline`, which is the duration that the acting leader will retry refreshing leadership before giving up. | | `BUILD_CONTROLLER_RETRY_PERIOD` | Override the `RetryPeriod`, which is the duration the LeaderElector clients should wait between tries of actions. | -| `BUILD_MAX_CONCURRENT_RECONCILES` | The number of concurrent reconciles by the build controller. A value of 0 or lower will use the default from the [controller-runtime controller Options](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/controller#Options). Default is 0. | -| `BUILDRUN_MAX_CONCURRENT_RECONCILES` | The number of concurrent reconciles by the buildrun controller. A value of 0 or lower will use the default from the [controller-runtime controller Options](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/controller#Options). Default is 0. | -| `BUILDSTRATEGY_MAX_CONCURRENT_RECONCILES` | The number of concurrent reconciles by the buildstrategy controller. A value of 0 or lower will use the default from the [controller-runtime controller Options](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/controller#Options). Default is 0. | -| `CLUSTERBUILDSTRATEGY_MAX_CONCURRENT_RECONCILES` | The number of concurrent reconciles by the clusterbuildstrategy controller. A value of 0 or lower will use the default from the [controller-runtime controller Options](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/controller#Options). Default is 0. | -| `KUBE_API_BURST` | Burst to use for the Kubernetes API client. See [Config.Burst](https://pkg.go.dev/k8s.io/client-go/rest#Config.Burst). A value of 0 or lower will use the default from client-go, which currently is 10. Default is 0. | -| `KUBE_API_QPS` | QPS to use for the Kubernetes API client. See [Config.QPS](https://pkg.go.dev/k8s.io/client-go/rest#Config.QPS). A value of 0 or lower will use the default from client-go, which currently is 5. Default is 0. | -| `TERMINATION_LOG_PATH` | Path of the termination log. This is where controller application will write the reason of its termination. Default value is `/dev/termination-log`. | -| `GIT_ENABLE_REWRITE_RULE` | Enable Git wrapper to setup a URL `insteadOf` Git config rewrite rule for the respective source URL hostname. Default is `false`. | +| `BUILD_MAX_CONCURRENT_RECONCILES` | The number of concurrent reconciles by the build controller. A value of 0 or lower will use the default from the [controller-runtime controller Options]. Default is 0. | +| `BUILDRUN_MAX_CONCURRENT_RECONCILES` | The number of concurrent reconciles by the BuildRun controller. A value of 0 or lower will use the default from the [controller-runtime controller Options]. Default is 0. | +| `BUILDSTRATEGY_MAX_CONCURRENT_RECONCILES` | The number of concurrent reconciles by the BuildStrategy controller. A value of 0 or lower will use the default from the [controller-runtime controller Options]. Default is 0. | +| `CLUSTERBUILDSTRATEGY_MAX_CONCURRENT_RECONCILES` | The number of concurrent reconciles by the ClusterBuildStrategy controller. A value of 0 or lower will use the default from the [controller-runtime controller Options]. Default is 0. | +| `KUBE_API_BURST` | Burst to use for the Kubernetes API client. See [Config.Burst]. A value of 0 or lower will use the default from client-go, which currently is 10. Default is 0. | +| `KUBE_API_QPS` | QPS to use for the Kubernetes API client. See [Config.QPS]. A value of 0 or lower will use the default from client-go, which currently is 5. Default is 0. | + +[^1]: The `runAsUser` and `runAsGroup` are dynamically overwritten depending on the build strategy that is used. See [Security Contexts](buildstrategies.md#security-contexts) for more information. ## Role-based Access Control @@ -43,11 +47,19 @@ The following roles are installed: - `shpwright-build-aggregate-view`: this role grants read access (get, list, watch) to most Shipwright Build objects. This includes `BuildStrategy`, `ClusterBuildStrategy`, `Build`, and `BuildRun` objects. - This role is aggregated to the [Kubernetes "view" role](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#default-roles-and-role-bindings). + This role is aggregated to the [Kubernetes "view" role]. - `shipwright-build-aggregate-edit`: this role grants write access (create, update, patch, delete) to Shipwright objects that are namespace-scoped. This includes `BuildStrategy`, `Builds`, and `BuildRuns`. Read access is granted to all `ClusterBuildStrategy` objects. - This role is aggregated to the [Kubernetes "edit" and "admin" roles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#default-roles-and-role-bindings). + This role is aggregated to the [Kubernetes "edit" and "admin" roles]. Only cluster administrators are granted write access to `ClusterBuildStrategy` objects. -This can be changed by creating a separate [Kubernetes `ClusterRole`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole) with these permissions and binding the role to appropriate users. +This can be changed by creating a separate [Kubernetes `ClusterRole`] with these permissions and binding the role to appropriate users. + +[Container]:https://pkg.go.dev/k8s.io/api/core/v1#Container +[controller-runtime controller Options]:https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/controller#Options +[Config.Burst]:https://pkg.go.dev/k8s.io/client-go/rest#Config.Burst +[Config.QPS]:https://pkg.go.dev/k8s.io/client-go/rest#Config.QPS +[Kubernetes "view" role]:https://kubernetes.io/docs/reference/access-authn-authz/rbac/#default-roles-and-role-bindings +[Kubernetes "edit" and "admin" roles]:https://kubernetes.io/docs/reference/access-authn-authz/rbac/#default-roles-and-role-bindings +[Kubernetes `ClusterRole`]:https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole diff --git a/content/en/docs/build/metrics.md b/content/en/docs/build/metrics.md index ef09fb8d..0abc5890 100644 --- a/content/en/docs/build/metrics.md +++ b/content/en/docs/build/metrics.md @@ -2,6 +2,11 @@ title: Build Controller Metrics linkTitle: Metrics --- + The Build component exposes several metrics to help you monitor the health and behavior of your build resources. diff --git a/content/en/docs/build/profiling.md b/content/en/docs/build/profiling.md index e0bd6e76..95e78b44 100644 --- a/content/en/docs/build/profiling.md +++ b/content/en/docs/build/profiling.md @@ -2,6 +2,11 @@ title: Build Controller Profiling linkTitle: Profiling --- + The build controller supports a `pprof` profiling mode, which is omitted from the binary by default. To use the profiling, use the controller image that was built with `pprof` enabled.