Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update e2e test cases for v1beta1 #1388

Merged
merged 2 commits into from
Oct 17, 2023
Merged

Update e2e test cases for v1beta1 #1388

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
92e7a0b
modifying the sample & documentation examples to refer v1beta1
apoorvajagtap Aug 8, 2023
f4f6eaa
Updates e2e tests for v1beta1
apoorvajagtap Sep 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ TEST_NAMESPACE ?= default
TEKTON_VERSION ?= v0.44.0

# E2E test flags
TEST_E2E_FLAGS ?= -p --randomize-all -timeout=1h -trace -v
TEST_E2E_FLAGS ?= -r -p --randomize-all -timeout=1h -trace -v

# E2E test service account name to be used for the build runs, can be set to generated to use the generated service account feature
TEST_E2E_SERVICEACCOUNT_NAME ?= pipeline
Expand Down Expand Up @@ -222,7 +222,7 @@ test-e2e-plain: ginkgo
TEST_E2E_SERVICEACCOUNT_NAME=${TEST_E2E_SERVICEACCOUNT_NAME} \
TEST_E2E_TIMEOUT_MULTIPLIER=${TEST_E2E_TIMEOUT_MULTIPLIER} \
TEST_E2E_VERIFY_TEKTONOBJECTS=${TEST_E2E_VERIFY_TEKTONOBJECTS} \
$(GINKGO) ${TEST_E2E_FLAGS} test/e2e
$(GINKGO) ${TEST_E2E_FLAGS} test/e2e/

.PHONY: test-e2e-kind-with-prereq-install
test-e2e-kind-with-prereq-install: ginkgo install-controller-kind install-strategies test-e2e-plain
Expand Down Expand Up @@ -270,7 +270,7 @@ install-controller-kind: install-apis

.PHONY: install-strategies
install-strategies: install-apis
kubectl apply -R -f samples/buildstrategy/
kubectl apply -R -f samples/v1beta1/buildstrategy/

.PHONY: local
local: install-strategies
Expand Down
226 changes: 106 additions & 120 deletions docs/build.md
View file
Open in desktop

Large diffs are not rendered by default.

99 changes: 49 additions & 50 deletions docs/buildrun.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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:

Expand Down Expand Up @@ -57,55 +57,57 @@ 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`.
_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:
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
Expand All @@ -116,7 +118,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
Expand All @@ -134,13 +136,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
Expand All @@ -154,18 +156,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.

Expand All @@ -181,12 +182,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
Expand All @@ -209,12 +210,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
Expand All @@ -231,7 +232,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
Expand Down Expand Up @@ -259,12 +260,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
Expand All @@ -277,12 +278,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
Expand All @@ -295,12 +296,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
Expand Down Expand Up @@ -370,22 +371,20 @@ 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.
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:

Expand Down
Loading