Skip to content

Shipwright Triggers API #1008

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

Merged
merged 3 commits into from
Jul 9, 2022
Merged

Shipwright Triggers API #1008

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
763ec21
Trigger API
otaviof Jun 21, 2022
0ca9a26
Generated Code and Kubernetes CRD
otaviof Jun 9, 2022
3f6ef66
Trigger API Documentation
otaviof Jun 9, 2022
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
162 changes: 162 additions & 0 deletions deploy/crds/shipwright.io_buildruns.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -466,6 +466,87 @@ spec:
should take to execute.
format: duration
type: string
trigger:
description: Trigger defines the scenarios where a new build should
be triggered.
properties:
secretRef:
description: SecretRef points to a local object carrying the
secret token to validate webhook request.
properties:
name:
description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
TODO: Add other useful fields. apiVersion, kind, uid?'
type: string
type: object
when:
description: When the list of scenarios when a new build should
take place.
items:
description: TriggerWhen a given scenario where the webhook
trigger is applicable.
properties:
github:
description: GitHub describes how to trigger builds
based on GitHub (SCM) events.
properties:
branches:
description: Branches slice of branch names where
the event applies.
items:
type: string
type: array
events:
description: Events GitHub event names.
items:
description: GitHubEventName set of WhenGitHub
valid event names.
type: string
minItems: 1
type: array
type: object
image:
description: Image slice of image names where the event
applies.
properties:
names:
description: Names fully qualified image names.
items:
type: string
type: array
type: object
name:
description: Name name or the short description of the
trigger condition.
type: string
objectRef:
description: ObjectRef describes how to match a foreign
resource, either using the name or the label selector,
plus the current resource status.
properties:
name:
description: Name target object name.
type: string
selector:
additionalProperties:
type: string
description: Selector label selector.
type: object
status:
description: Status object status.
items:
type: string
type: array
type: object
type:
description: Type the event type
type: string
required:
- name
- type
type: object
type: array
type: object
volumes:
description: Volumes contains volume Overrides of the BuildStrategy
volumes in case those are allowed to be overridden. Must only
Expand Down Expand Up @@ -4190,6 +4271,87 @@ spec:
should take to execute.
format: duration
type: string
trigger:
description: Trigger defines the scenarios where a new build should
be triggered.
properties:
secretRef:
description: SecretRef points to a local object carrying the
secret token to validate webhook request.
properties:
name:
description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
TODO: Add other useful fields. apiVersion, kind, uid?'
type: string
type: object
when:
description: When the list of scenarios when a new build should
take place.
items:
description: TriggerWhen a given scenario where the webhook
trigger is applicable.
properties:
github:
description: GitHub describes how to trigger builds
based on GitHub (SCM) events.
properties:
branches:
description: Branches slice of branch names where
the event applies.
items:
type: string
type: array
events:
description: Events GitHub event names.
items:
description: GitHubEventName set of WhenGitHub
valid event names.
type: string
minItems: 1
type: array
type: object
image:
description: Image slice of image names where the event
applies.
properties:
names:
description: Names fully qualified image names.
items:
type: string
type: array
type: object
name:
description: Name name or the short description of the
trigger condition.
type: string
objectRef:
description: ObjectRef describes how to match a foreign
resource, either using the name or the label selector,
plus the current resource status.
properties:
name:
description: Name target object name.
type: string
selector:
additionalProperties:
type: string
description: Selector label selector.
type: object
status:
description: Status object status.
items:
type: string
type: array
type: object
type:
description: Type the event type
type: string
required:
- name
- type
type: object
type: array
type: object
volumes:
description: Volumes contains volume Overrides of the BuildStrategy
volumes in case those are allowed to be overridden. Must only
Expand Down
81 changes: 81 additions & 0 deletions deploy/crds/shipwright.io_builds.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -444,6 +444,87 @@ spec:
should take to execute.
format: duration
type: string
trigger:
description: Trigger defines the scenarios where a new build should
be triggered.
properties:
secretRef:
description: SecretRef points to a local object carrying the secret
token to validate webhook request.
properties:
name:
description: 'Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
TODO: Add other useful fields. apiVersion, kind, uid?'
type: string
type: object
when:
description: When the list of scenarios when a new build should
take place.
items:
description: TriggerWhen a given scenario where the webhook
trigger is applicable.
properties:
github:
description: GitHub describes how to trigger builds based
on GitHub (SCM) events.
properties:
branches:
description: Branches slice of branch names where the
event applies.
items:
type: string
type: array
events:
description: Events GitHub event names.
items:
description: GitHubEventName set of WhenGitHub valid
event names.
type: string
minItems: 1
type: array
type: object
image:
description: Image slice of image names where the event
applies.
properties:
names:
description: Names fully qualified image names.
items:
type: string
type: array
type: object
name:
description: Name name or the short description of the trigger
condition.
type: string
objectRef:
description: ObjectRef describes how to match a foreign
resource, either using the name or the label selector,
plus the current resource status.
properties:
name:
description: Name target object name.
type: string
selector:
additionalProperties:
type: string
description: Selector label selector.
type: object
status:
description: Status object status.
items:
type: string
type: array
type: object
type:
description: Type the event type
type: string
required:
- name
- type
type: object
type: array
type: object
volumes:
description: Volumes contains volume Overrides of the BuildStrategy
volumes in case those are allowed to be overridden. Must only contain
Expand Down
104 changes: 104 additions & 0 deletions docs/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ SPDX-License-Identifier: Apache-2.0
- [Defining the Output](#defining-the-output)
- [Defining Retention Parameters](#defining-retention-parameters)
- [Defining Volumes](#defining-volumes)
- [Defining Triggers](#defining-triggers)
- [BuildRun deletion](#BuildRun-deletion)

## Overview
Expand Down Expand Up @@ -602,6 +603,109 @@ spec:
name: test-config
```

### 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.

**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
kind: Build
spec:
source:
url: https://github.com/shipwright-io/sample-go
contextDir: docker-build
credentials:
name: webhook-secret
trigger:
when: []
```

Certain types of events will use attributes defined on `.spec.source` to complete the information needed in order to dispatch events.

#### 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`.

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")

The following snippet shows a configuration machting `Push` and `PullRequest` events on the `main` branch, for example:

```yaml
# [...]
spec:
source:
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should not here be the name of the Image resource that must be in the same namespace ? Especially if the image is not at all in an external registry, it would be complicated to provide such an image name.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here we are looking for a fully qualified image name and to later on rely on the image controller to handle this business logic. However, the image name is a free form string initially.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/cc @ricardomaraschini

```

#### 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
Comment on lines +704 to +705
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I may need to check the ship again, why do we filter on the status here? Should not it be always on successful completion?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In order to have a flexible workflow we should allow any state to be filled in, and it's expected that "Succeeded" is the most common.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Flexibility is fine, but out of interest, what would be the use case to trigger a BuildRun on a Pipeline status change other than to Succeeded?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "status" is reported as a string, and the .objectRef can match more than one type of Kubernetes CRD.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just for my understanding, does Pipeline CRD has a state, or is more about PipelineRun states?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I haven't been clear before. The object that carries the state is the PipelineRun.

name: tekton-pipeline-name
```

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about the BuildRun trigger? In my own subjective opinion, that is more important than pipelines.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The triggers is a mechanism to instantiate BuildRun objects based on a Build, so BuildRun would not be able to trigger itself.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, I meant Build trigger. But I just notice it is not part of the SHIP, then it is fine for now. It is being discussed here: shipwright-io/community#75 (comment).

### Sources

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.
Expand Down
Loading