From de22ae91d261d35425470d5c52fb8c14f1566a36 Mon Sep 17 00:00:00 2001 From: Apoorva Jagtap Date: Mon, 21 Aug 2023 14:05:37 +0530 Subject: [PATCH] updated doc --- docs/build.md | 225 +++++++++------------ docs/buildrun.md | 98 +++++---- docs/buildstrategies.md | 40 ++-- docs/development/authentication.md | 21 +- docs/development/testing.md | 9 +- docs/tutorials/building_with_buildkit.md | 12 +- docs/tutorials/building_with_buildpacks.md | 12 +- docs/tutorials/building_with_kaniko.md | 12 +- 8 files changed, 201 insertions(+), 228 deletions(-) diff --git a/docs/build.md b/docs/build.md index cb6a5b934e..75dcc4c4f2 100644 --- a/docs/build.md +++ b/docs/build.md @@ -25,14 +25,14 @@ SPDX-License-Identifier: Apache-2.0 A `Build` resource allows the user to define: - source -- sources (**this is deprecated, and will be removed in a future release**) +- trigger - strategy -- params -- builder -- dockerfile +- paramValues - output +- timeout - env - retention +- volumes A `Build` is available within a namespace. @@ -45,9 +45,9 @@ 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 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 @@ -64,9 +64,9 @@ To prevent users from triggering `BuildRuns` (_execution of a Build_) that will | 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-paramvalues) 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. | +| 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 | 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. | @@ -76,21 +76,17 @@ To prevent users from triggering `BuildRuns` (_execution of a Build_) that will 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 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 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_) **This field has been deprecated, and will be removed in a future release.** - `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_). **This field has been deprecated, and will be removed in a future release.** - - `spec.sources` - [Sources](#sources) describes a slice of artifacts that will be imported into the project context before the actual build process starts. **This field has been deprecated, and will be removed in a future release.** - `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.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. @@ -103,19 +99,17 @@ The `Build` definition supports the following fields: A `Build` resource can specify a Git repository or bundle image source, 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.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 @@ -123,63 +117,67 @@ metadata: build.shipwright.io/verify.repository: "true" spec: source: - url: https://github.com/shipwright-io/sample-go + 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 + 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 + git: + url: https://github.com/SaschaSchwarze0/npm-simple contextDir: renamed ``` 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 + 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 + git: + url: https://github.com/shipwright-io/sample-go contextDir: docker-build env: - name: EXAMPLE_VAR_1 @@ -192,13 +190,14 @@ 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 + git: + url: https://github.com/shipwright-io/sample-go contextDir: docker-build env: - name: POD_NAME @@ -211,13 +210,14 @@ 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 + git: + url: https://github.com/shipwright-io/sample-go contextDir: docker-build env: - name: MEMORY_LIMIT @@ -241,7 +241,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 @@ -271,7 +271,7 @@ In general, _paramValues_ are tightly bound to Strategy _parameters_. Please mak The [BuildKit sample `BuildStrategy`](../samples/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 @@ -287,14 +287,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 @@ -327,7 +327,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 @@ -350,7 +350,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 @@ -376,7 +376,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 @@ -419,10 +419,10 @@ Here, we pass three items in the `build-args` array: **Note: Builder and Dockerfile options are deprecated, and will be removed in a future release.** -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 @@ -433,13 +433,16 @@ spec: strategy: name: buildah kind: ClusterBuildStrategy - dockerfile: Dockerfile + paramValues: + - name: dockerfile + values: + - 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 @@ -450,8 +453,10 @@ spec: strategy: name: source-to-image kind: ClusterBuildStrategy - builder: - image: docker.io/centos/nodejs-10-centos7 + paramValues: + - name: builder-image + values: + - value: "docker.io/centos/nodejs-10-centos7" ``` ### Defining the Output @@ -463,19 +468,22 @@ A `Build` resource can specify the output where it should push the image. For ex 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 + 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 + values: + - value: "docker.io/centos/nodejs-10-centos7" output: image: image-registry.openshift-image-registry.svc:5000/build-examples/nodejs-ex ``` @@ -483,45 +491,49 @@ 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 + values: + - 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 + 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 + values: + - 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" @@ -556,13 +568,14 @@ 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" + git: + url: "https://github.com/shipwright-io/sample-go" contextDir: docker-build strategy: kind: ClusterBuildStrategy @@ -579,8 +592,6 @@ An example of a user using both TTL and Limit retention fields. In case of such ### Defining Volumes -**Note: The `spec.volumes[].description` field is deprecated, and will be removed in a future release.** - `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. @@ -590,17 +601,21 @@ 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 + git: + url: https://github.com/example/url strategy: name: buildah kind: ClusterBuildStrategy - dockerfile: Dockerfile + paramValues: + - name: dockerfile + values: + - value: Dockerfile output: image: registry/namespace/image:latest volumes: @@ -618,14 +633,14 @@ Using the triggers, you can submit `BuildRun` instances when certain events happ 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 spec: source: - url: https://github.com/shipwright-io/sample-go + git: + url: https://github.com/shipwright-io/sample-go + cloneSecret: webhook-secret contextDir: docker-build - credentials: - name: webhook-secret trigger: when: [] ``` @@ -634,21 +649,22 @@ Certain types of events will use attributes defined on `.spec.source` to complet #### GitHub -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.url` combined with the attributes on `.spec.trigger.when[].github`. +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`. 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: - 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.revision` -- If `spec.source.revision` is empty, the default revision name is used ("main") +- 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") -The following snippet shows a configuration machting `Push` and `PullRequest` events on the `main` branch, for example: +The following snippet shows a configuration matching `Push` and `PullRequest` events on the `main` branch, for example: ```yaml # [...] spec: source: - url: https://github.com/shipwright-io/sample-go + git: + url: https://github.com/shipwright-io/sample-go trigger: when: - name: push and pull-request on the main branch @@ -711,44 +727,3 @@ spec: - Succeeded name: tekton-pipeline-name ``` - -### Sources - -**Note: This feature has been deprecated, and will be removed in a future release**. - -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. - -```yaml -apiVersion: shipwright.io/v1alpha1 -kind: Build -metadata: - name: nodejs-ex -spec: - sources: - - name: project-logo - url: https://gist.github.com/project/image.png -``` - -Under `.spec.sources` are the following attributes: - -- `.name`: represents the name of the resource, required attribute. -- `.url`: universal resource location (URL), required attribute. - -When downloading artifacts, the process is executed in the same directory where the application source-code is located, by default `/workspace/source`. - -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. - -At this initial stage, authentication is not supported; therefore, you can only download from sources without this mechanism in place. - -## BuildRun deletion - -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 -apiVersion: shipwright.io/v1alpha1 -kind: Build -metadata: - name: kaniko-golang-build - annotations: - build.shipwright.io/build-run-deletion: "true" -``` diff --git a/docs/buildrun.md b/docs/buildrun.md index 093ac7930e..7351b61c86 100644 --- a/docs/buildrun.md +++ b/docs/buildrun.md @@ -9,8 +9,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-buildref) + - [Defining the Build Specification](#defining-the-buildspec) - [Defining ParamValues](#defining-paramvalues) - [Defining the ServiceAccount](#defining-the-serviceaccount) - [Defining Retention Parameters](#defining-retention-parameters) @@ -28,7 +28,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: @@ -57,55 +57,55 @@ 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.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.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`. - -### 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: + 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 ParamValues @@ -116,7 +116,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 @@ -134,13 +134,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 @@ -154,18 +154,17 @@ 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. **This field is deprecated, and will be removed in a future release.** +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. @@ -181,12 +180,12 @@ 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 @@ -209,12 +208,12 @@ 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 @@ -231,7 +230,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 @@ -259,12 +258,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 @@ -277,12 +276,12 @@ 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 @@ -295,12 +294,12 @@ 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 @@ -370,21 +369,18 @@ The following table illustrates the different states a BuildRun can have under i | 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 | 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. - -In addition, the `status.conditions` hosts a compacted message under the' message' field that contains the `kubectl` command to trigger and retrieve the logs. +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. +Users can check the `status.failureDetails` field, which includes a detailed failure reason and message. The message and reason are only included if the build strategy provides them. Example of failed BuildRun: diff --git a/docs/buildstrategies.md b/docs/buildstrategies.md index acaee6b038..aa17e9c7c7 100644 --- a/docs/buildstrategies.md +++ b/docs/buildstrategies.md @@ -46,7 +46,7 @@ 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. @@ -271,7 +271,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 @@ -299,7 +299,7 @@ The following example is from the [BuildKit sample build strategy](../samples/bu ```yaml --- -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: buildkit @@ -322,7 +322,7 @@ spec: description: "The secrets to pass to the build. Values must be in the format ID=FILE_CONTENT." type: array defaults: [] - buildSteps: + steps: ... - name: build-and-push image: moby/buildkit:nightly-rootless @@ -460,7 +460,7 @@ spec: - name: sample-parameter description: A sample parameter type: string - buildSteps: + steps: - name: sample-step command: - /bin/bash @@ -491,7 +491,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 @@ -514,7 +514,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 @@ -544,7 +544,7 @@ You can look at sample build strategies, such as [Buildpacks](../samples/buildst 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: @@ -567,7 +567,7 @@ Error details are only propagated if the build container terminates with a non-z 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: @@ -608,12 +608,12 @@ 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.13.0 workingDir: $(params.shp-source-root) @@ -652,12 +652,12 @@ spec: cpu: 250m memory: 65Mi --- -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.13.0 workingDir: $(params.shp-source-root) @@ -701,18 +701,22 @@ The above provides more control and flexibility for the strategy admins. For `en ```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 + values: + - value: Dockerfile ``` ### How does Tekton Pipelines handle resources @@ -947,12 +951,12 @@ 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.27.0 workingDir: $(params.shp-source-root) diff --git a/docs/development/authentication.md b/docs/development/authentication.md index 312b9be54b..ff1c07fc03 100644 --- a/docs/development/authentication.md +++ b/docs/development/authentication.md @@ -105,29 +105,29 @@ Depending on the secret type, there are two ways of doing this: When using ssh auth, users should follow: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: - url: git@gitlab.com:eduardooli/newtaxi.git - credentials: - name: secret-git-ssh-auth + git: + url: git@gitlab.com:eduardooli/newtaxi.git + cloneSecret: secret-git-ssh-auth ``` When using basic auth, users should follow: ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: - url: https://gitlab.com/eduardooli/newtaxi.git - credentials: - name: secret-git-basic-auth + git: + url: https://gitlab.com/eduardooli/newtaxi.git + cloneSecret: secret-git-basic-auth ``` ## Authentication to container registries @@ -156,15 +156,14 @@ With the right secret in place (_note: Ensure creation of secret in the proper K For container registries, the secret should be placed under the `spec.output.credentials` path. ```yaml -apiVersion: shipwright.io/v1alpha1 +apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build ... output: image: docker.io/foobar/sample:latest - credentials: - name: + pushSecret: ``` ## References diff --git a/docs/development/testing.md b/docs/development/testing.md index 86025b4580..7aed4eb1ad 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -128,8 +128,7 @@ The following table contains a list of environment variables that will override | Environment Variable | Path | Description | |------------------------------------|--------------------------------|-----------------------------------------------------| | `TEST_IMAGE_REPO` | `spec.output.image` | Image repository for end-to-end tests | -| `TEST_IMAGE_REPO_INSECURE` | `spec.output.insecure` | Flag whether the image repository is secure or not. | -| `TEST_IMAGE_REPO_SECRET` | `spec.output.credentials.name` | Container credentials secret name | +| `TEST_IMAGE_REPO_SECRET` | `spec.output.pushSecret` | Container credentials secret name | | `TEST_IMAGE_REPO_DOCKERCONFIGJSON` | _none_ | JSON payload equivalent to `~/.docker/config.json` | The contents of `TEST_IMAGE_REPO_DOCKERCONFIGJSON` can be obtained from [quay.io](https://quay.io) using a [robot account](https://docs.quay.io/glossary/robot-accounts.html). The JSON payload is for example: @@ -155,9 +154,9 @@ End-to-end tests can also be executed with the context of private Git repositori | Environment Variable | Path | Description | |-----------------------|--------------------------------|---------------------------------------| | `TEST_PRIVATE_REPO` | _none_ | Enable private repository e2e tests | -| `TEST_PRIVATE_GITHUB` | `spec.source.url` | Private URL, like `git@github.com` | -| `TEST_PRIVATE_GITLAB` | `spec.source.url` | Private URL, like `git@gitlab.com` | -| `TEST_SOURCE_SECRET` | `spec.source.credentials.name` | Private repository credentials | +| `TEST_PRIVATE_GITHUB` | `spec.source.git.url` | Private URL, like `git@github.com` | +| `TEST_PRIVATE_GITLAB` | `spec.source.git.url` | Private URL, like `git@gitlab.com` | +| `TEST_SOURCE_SECRET` | `spec.source.git.cloneSecret` | Private repository credentials | On using `TEST_SOURCE_SECRET`, the environment variable must contain the name of the Kubernetes Secret containing SSH private key, for given private Git repository. See the [docs](authentication.md) for more information about authentication methods in the Build. diff --git a/docs/tutorials/building_with_buildkit.md b/docs/tutorials/building_with_buildkit.md index 82975818f0..36f392ecc8 100644 --- a/docs/tutorials/building_with_buildkit.md +++ b/docs/tutorials/building_with_buildkit.md @@ -54,21 +54,21 @@ Let's apply our Build and wait for it to be ready: ```bash $ export REGISTRY_ORG= $ cat < $ cat < $ cat <