Add customization examples #122
Conversation
|
/ok-to-test |
|
🚀 Preview is available at https://pr-122--konflux-docs.netlify.app |
| - name: clone-repository-oci-ta | ||
| params: | ||
| - name: url | ||
| value: $(params.git-url) | ||
| - name: revision | ||
| value: $(params.revision) | ||
| - name: ociStorage | ||
| # needs to be unique storage name | ||
| value: $(params.output-image).git | ||
| runAfter: | ||
| - init | ||
| taskRef: | ||
| params: | ||
| - name: name | ||
| value: git-clone-oci-ta | ||
| - name: bundle | ||
| value: quay.io/konflux-ci/tekton-catalog/task-git-clone-oci-ta@sha256:0f4360ce144d46171ebd2e8f4d4575539a0600e02208ba5fc9beeb2c27ddfd4c | ||
| - name: kind | ||
| value: task | ||
| resolver: bundles | ||
| workspaces: | ||
| # use the git-auth workspace for credentials | ||
| - name: basic-auth | ||
| workspace: git-auth |
There was a problem hiding this comment.
This looks like the definition for the default git-clone task. Are you suggesting that users add this or are you just using this as an example to show the different parts? If the latter, I think we should use a different pattern.
There was a problem hiding this comment.
If we want to use the TA for custom tasks to comply with the EC, we have to use the quay.io/konflux-ci/tekton-catalog/task-git-clone-oci-ta. We had to add it as a new task.
It is practically the same as the default task. But the default task uses workspaces which means custom tasks will breach the EC.
| # needs to be unique storage name | ||
| value: $(params.output-image).git |
There was a problem hiding this comment.
It needs to be globally unique within the pipeline definition, righ?
There was a problem hiding this comment.
Yes. I'll make the comment more specific
| # make sure the task runs after the artifact is created | ||
| runAfter: | ||
| - clone-repository-oci-ta |
There was a problem hiding this comment.
Is this strictly necessary? Tekton should be able to order the TaskRuns (but the visualization may be better with the runAfters defined.
There was a problem hiding this comment.
I wanted to make it obvious and follow the pattern of the generated tekton config provided by Konflux.
| runAfter: | ||
| - clone-repository-oci-ta | ||
| params: | ||
| # store the trusted artifact |
There was a problem hiding this comment.
This implies that we are storing the artifact here, but we are not. We are resolving the OCI artifact that has been previously stored, right?
There was a problem hiding this comment.
Correct. Poor choice of words.
| taskSpec: | ||
| params: | ||
| - description: The Trusted Artifact URI pointing to the artifact with the application source code. | ||
| name: SOURCE_ARTIFACT | ||
| type: string | ||
| volumes: | ||
| # New volume to store a copy of the source code accessible only to this Task. | ||
| - name: workdir | ||
| emptyDir: {} | ||
|
|
||
| stepTemplate: | ||
| volumeMounts: | ||
| - mountPath: /var/workdir | ||
| name: workdir | ||
| steps: | ||
| # Add the trusted artifact to the task volume | ||
| - name: use-trusted-artifact | ||
| image: quay.io/redhat-appstudio/build-trusted-artifacts:latest@sha256:8391272c4e5011120e9e7fee2c1f339e9405366110bf239dadcbc21e953ce099 | ||
| args: | ||
| - use | ||
| - $(params.SOURCE_ARTIFACT)=/var/workdir/source | ||
| - name: task-run | ||
| # set the working directory to value from previous step | ||
| workingDir: /var/workdir/source | ||
| # Use image that suites your use case | ||
| image: registry.access.redhat.com/ubi8/minimal | ||
| securityContext: | ||
| # If the task step needs write access to the volume, set the runAsUser to 0 (root). | ||
| runAsUser: 0 | ||
| script: | | ||
| #!/bin/bash | ||
| # Execute the task |
There was a problem hiding this comment.
This ends up being a lot of rendered yaml content. Would it be better to just reference an example in some repository that has the content annotated, to reference some annotated "sample" task definition that has the required steps, or to just have smaller snippets of code isolated to the specific requirements?
There was a problem hiding this comment.
We have a sample here: https://github.com/RedHatInsights/chrome-service-backend/blob/main/.tekton/chrome-service-pull-request.yaml#L476-L514
If you prefer linking to an existing example I ok with that.
| You can add sidecar containers to the build pipeline to run additional tasks alongside the main container. For example, you can add a sidecar container to run a database to enable your unit tests to run against a real database. | ||
|
|
||
| In the example, we add a sidecar container to task to run a PostgreSQL database. Such sidecar can be used to test database seeding, migrations, etc. |
There was a problem hiding this comment.
Is the primary use case for this unit tests? If so, should we add this to the testing pages?
There was a problem hiding this comment.
Is the primary use case for this unit tests?
Correct.
| - name: use-trusted-artifact | ||
| image: quay.io/redhat-appstudio/build-trusted-artifacts:latest@sha256:8391272c4e5011120e9e7fee2c1f339e9405366110bf239dadcbc21e953ce099 | ||
| args: | ||
| - use | ||
| - $(params.SOURCE_ARTIFACT)=/var/workdir |
There was a problem hiding this comment.
I guess that this is just needed if your sidecar content is pulled from the git source? This code snippet isn't in the TA section so we need to be careful about the actual content we include without explaining it further.
There was a problem hiding this comment.
It is yeah. The main purpose of these examples is to show how to extend pipelines with custom tasks and comply with the EC. But I can see your point. Maybe instead of these full examples, it should be made very obvious that pipeline customizations need a different approach, especially if the builds are using "external" policies not defined by the project itself.
| - mountPath: /var/workdir | ||
| name: workdir | ||
| # define the sidecar containers | ||
| sidecars: |
There was a problem hiding this comment.
The content of this feels too specific again which results in the snippet being too large.
There was a problem hiding this comment.
We can link to an existing example if you'd like.
| steps: | ||
| # Add the trusted artifact to the task volume | ||
| - name: use-trusted-artifact | ||
| image: quay.io/redhat-appstudio/build-trusted-artifacts:latest@sha256:8391272c4e5011120e9e7fee2c1f339e9405366110bf239dadcbc21e953ce099 |
There was a problem hiding this comment.
We should use pullspecs from quay.io/konflux-ci wherever possible.
There was a problem hiding this comment.
Is there an equivalent spec in the konflux-ci org? I did not find any.
| If you are using the Enterprise Contract (EC) to verify your builds, you can extend the build pipeline with your own tasks using Trusted Artifacts. Trusted Artifacts allow you to share data between Tasks in a secure way. For example, the `task-git-clone` task, has Trusted Artifacts version called `task-git-clone-oci-ta`. | ||
| [NOTE] | ||
| ==== | ||
| You can find more tasks link:https://quay.io/organization/konflux-ci[here]. Task generating Trusted Artifacts have `-oci-ta` suffix. |
There was a problem hiding this comment.
Should we link to quay or to the build definitions?
There was a problem hiding this comment.
We could link here: https://github.com/konflux-ci/build-definitions/tree/main/task, these do not have the image repository links. So one does not really know form where to pull the images. So right now, probably link to both?
Signed-off-by: Martin Marosi <[email protected]> Signed-off-by: Martin Marosi <[email protected]>
Hyperkid123
force-pushed
the
add-customization-examples
branch
from
6bd10ef
to
96d565a
Compare
|
@arewm I've updated the PR. Removed some of the YAML and moved the sidecar example to the testing section. I've also added links to existing pipelines so folks can get the full context. I am not linking directly to the task's code lines. They will likely change in the future and the links might lead to a different spec. Let me know what you think 🙂 . |
Based on a conversation with the Konflux engineers, I've added a couple of examples to the docs which might help others in the future.
Changes