Skip to content

Commit

Permalink
doc: add the Artifact construction ADR
Browse files Browse the repository at this point in the history
Signed-off-by: dirgim <kpavic@redhat.com>

rh-pre-commit.version: 2.2.0
rh-pre-commit.check-secrets: ENABLED
  • Loading branch information
dirgim committed Oct 23, 2024
1 parent 3720837 commit cf40d38
Showing 1 changed file with 95 additions and 0 deletions.
95 changes: 95 additions & 0 deletions ADR/0041-integration-service-upstreaming.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# XX. Creating Artifacts from Snapshots for testing and release

Date: 2024-10-21

## Status

Proposed

## Authors

- Krunoslav Pavic
- Andrew McNamara

## Context

This ADR aims to cover the proposed functionality for creating additional Artifacts as part of the Konflux build/test/release process.
These artifacts would vary in type and would cover use cases where either the single built image or entire sets of images
from the user's application are needed to generate one or more artifacts.

## Use Cases in Detail

* A team produces operands and operators. When integration service creates a Snapshot, it uses a constructor that
actually builds a bundle. When releasing, the team releases that single bundle artifact. That constructor also has an extract
operation to list all related images that are referenced, and that extraction generates the list for release service to operate on
* A team produces a set of images with ko. The build task generates/pushes all images with ko and then produces a "build artifact"
OCI manifest which includes an immutable reference to each of the ko-built artifacts. When integration service creates a Snapshot,
it uses a constructor that doesn't need to create a new artifact. When releasing, the team releases that single artifact.
The constructor also has an extract operation to list all the ko-built artifacts and that extraction generates the list for release service to operate on.
* A team produces a set of images that are just a group of artifacts that should be released together.
The artifacts are built via separate PipelineRuns. When integration service creates a Snapshot, it uses a constructor
that saves the Snapshot CR as an OCI blob. When releasing, the team releases that single artifact.
The constructor also has an extract operation to list all artifacts that were in the Snapshot and that extraction
generates the list for release service to operate on.


## Decision

A new API will be introduced which instructs the Integration service to create a Tekton pipeline which will generate the
artifact.
Once built, the artifact reference will be added to the Snapshot's metadata so it can be discovered during testing or release process.
Additionally, the integration service will wait for the pipelines to finish before starting the integration testing pipelines
in order to enable users to run tests using the new artifacts.

### The ArtifactConstructor API

The proposal here is to introduce the new ArtifactConstructor API which will define Tekton pipelines that will generate individual artifacts.
These pipelines would be executed after a Snapshot is generated and before the integration test pipelines start.

When each artifact generation pipelineRun is completed, the reference to the artifact is extracted and added to the Snapshot.
After that, the integration testing pipelines castart, and since the artifacts are referenced by the Snapshot,
it is possible to fetch them and run tests on them.

```yaml
apiVersion: appstudio.redhat.com/v2alpha1
kind: ArtifactConstructor
metadata:
name: example--artifact-constructor
spec:
selectors:
- expression: ‘metadata.labels["konflux-ci.dev/application"] == "integration-service" && metadata.annotations["test.pac.appstudio.openshift.io/event-type"] == "pull_request"’
description: “Selects only PR Snapshots associated with integration-service”
resolverRef:
resolver: git
params:
- name: url
value: https://github.com/konflux-ci/integration-examples
- name: revision
value: main
- name: pathInRepo
value: pipelines/bundle_generator_pipeline.yaml
extractors:
- ref: 'status.results.filter(result,result.name == "IMAGE_URL")[0].value'
name: ‘metadata.labels["appstudio.openshift.io/component"]’

```

Don't take the fields literally. The details will likely change after the ADR has settled. It is
here for illustration purposes.

The `selector` field will be used to identify resources that should trigger the construction of new Artifacts. This will be done using CEL expressions.

The `resolverRef` resource will be used to define the Tekton pipeline definition which can be used to run the artifact pipelineRun.

The `extractor` resource will use CEL expressions to extract the individual field values from the artifact pipelineRun.
The individual artifacts are expected to use a reference that can be used to fetch it, like an image pullSpec or similar URL.
Since the `extractor` resource is a list, it can take multiple extractor entries if the artifact pipeline is expected to provide multiple artifacts.
Each extracted resource will be added to the Snapshot's metadata.

## Consequences

- [integration-service] now executes additional Tekton pipelineRuns which are expected to generate artifacts which
can then be associated with the Snapshot.
- [integration-service] waits for the artifact pipelineRuns to finish before starting the integration testing pipelines
for a given Snapshot.

0 comments on commit cf40d38

Please sign in to comment.