Customizing Red Hat Trusted Application Pipeline

Procedure

1. Clone your forked tssc-sample-templates repository, and then open it in your preferred text editor, such as Visual Studio Code.

2. Locate the properties file within your project directory. This file stores the default values that you can customize. Open it for editing and update the following key-value pairs according to your environment.

   Key	Description
   export GITHUB_DEFAULT_HOST	Set this to your on-prem GitHub host fully qualified domain name. That is, the URL without the HTTP protocol and without the .git extension. For example github-github.apps.cluster-ljg9z.sandbox219.opentlc.com. Default is github.com.
   export GITLAB_DEFAULT_HOST	Set this to your on-prem GitLab host host fully qualified domain name. That is, the URL without the HTTP protocol and without the .git extension. For example gitlab-gitlab.apps.cluster-ljg9z.sandbox219.opentlc.com. Default is gitlab.com.
   export QUAY_DEFAULT_HOST	The default Quay URL corresponds to your specific on-prem image registry URL without the HTTP protocol. For example, quay-tv2pb.apps.cluster-tv2pb.sandbox1194.opentlc.com. The default quay host is quay.io.
   export DEFAULT_DEPLOYMENT_NAMESPACE_PREFIX	The namespace prefix for deployments within RHTAP. Default is rhtap-app. Note Update this if you have modified the default trusted-application-pipeline: namespace during the RHTAP installation process.
   export PIPELINE_REPO_URL	The URL of the forked pipeline repository. For example, https://github.com/redhat-appstudio/tssc-sample-pipelines.
   export PIPELINE_REPO_BRANCH	The branch of the forked pipeline repository to which you want to point. For example, main.
   export GITHUB_DEFAULT_ORG	The name of your GitHub organization that you want to set as default.
   export QUAY_DEFAULT_ORG	The name of your Quay organization that you want to set as default.

   Figure 1.1. The properties file

   

3. Run the generate.sh script in your terminal. This action adjusts the software templates, replacing default host values with your specified inputs.

   Copy to Clipboard Toggle word wrap

   ./generate.sh

   Figure 1.2. The generate.sh script

   

4. For Jenkins only: To customize your Jenkins library, navigate to skeleton > ci > gitops-template > jenkins, and open Jenkinsfile. Replace the remote URL with the URL of your forked repository. For example, remote: 'https://github.com/<username>/tssc-sample-jenkins.git'.

   Additionally, if your Jenkins is on a non-local OpenShift instance, and your Rekor and TUF services are on different clusters, update the REKOR_HOST and TUF_MIRROR environment variables. You can configure these variables in the env.sh file within the component repository or set them as environment variables or secrets in Jenkins. This configuration ensures that your external Jenkins server can communicate with Rekor and TUF installed with RHTAP. Without this, RHTAP might not sign container images correctly in the Jenkins pipeline.

   To update the REKOR_HOST and TUF_MIRROR variables:

   1. Open the env.sh file via skeleton > ci > gitops-template > jenkins > rhtap.

      The second env.sh file is located at skeleton > ci > source-repo > jenkins > rhtap. Pick the one that suits your needs or update both.

      In env.sh, review the default values for REKOR_HOST and TUF_MIRROR:

      Copy to Clipboard Toggle word wrap

      REKOR_HOST=http://rekor-server.rhtap-tas.svc
      TUF_MIRROR=http://tuf.rhtap-tas.svc

   2. Replace .svc with your OpenShift cluster URL. The .svc domain refers to the local cluster, and internal services can access other services with .svc in their routes, but an external Jenkins cannot.

      The correct routes of the Rekor and TUF services are printed as part of the installation process of RHTAP. If these data aren’t available to you, run this command in your CLI and select the Rekor and TUF routes in the output:

      Copy to Clipboard Toggle word wrap

      $ oc get routes -n rhtap-tas

      An example of a Rekor server URL: http://rekor-server.rhtap-tas.apps.rosa.j6ufg-t3htv-ts6.z797.p3.openshiftapps.com.

   Note
   • To configure environment variables or secrets in Jenkins see, Adding secrets to Jenkins for secure integration with external tools.
   • By default, RHTAP uses dynamically loaded Jenkins libraries. If you need to configure RHTAP to use built-in Jenkins libraries instead of dynamic loading, you must modify the Jenkins provisioning setup. This change can improve traceability and Red Hat Enterprise Contract (Enterprise Contract) attestations. For detailed instructions, see Configuring RHTAP to use built-in Jenkins libraries.
5. For RHACS only: To enable RHACS scans, set the export DISABLE_ACS to false in the env.sh file.

6. Commit and push the changes to your repository. This automatically updates the template in RHDH. Alternatively, you can import and refresh a single or all customized templates directly in RHDH.

   1. Go to your forked sample template repository on your Git provider.
   2. For a single template, from the templates directory, select template.yaml. Copy its URL from the browser address bar. For example, https://github.com/<username>/tssc-sample-templates/blob/main/templates/devfile-sample-code-with-quarkus-dance/template.yaml. Otherwise, for all the templates, select all.yaml and copy its URL from the browser address bar. For example, https://github.com/<username>/tssc-sample-templates/blob/main/all.yaml.
   3. Switch back to RHDH platform.
   4. Select Create > Register Existing Component.
   5. In the Select URL field, paste the appropriate URL that you copied in Step 4b.
   6. Select Analyze and then select Import to update the templates in RHDH.

Procedure

1. Access forked sample pipelines repository URL:

   1. Open your forked sample pipelines repository.
   2. Copy the complete URL from the address bar. For example, https://github.com/<username>/tssc-sample-pipelines.

2. Update pac URLs in the sample templates repository:

   1. Navigate to your local cloned sample templates repository using your terminal.
   2. Run the following command, replacing {fork_url} with the copied URL from step 1 and {branch_name} with your desired branch name (for example, main):
   Copy to Clipboard Toggle word wrap

   ./scripts/update-tekton-definition {fork_url} {branch_name}
   
   # For example, .scripts/update-tekton-definition https://github.com/<username>/tssc-sample-pipelines main

3. Review, commit, and push changes:

   1. Review the updated files within your sample templates repository.
   2. Commit the changes with appropriate message.
   3. Push the committed changes to your forked repository.

Procedure

1. Create a directory for the build resources. The location of the directory depends on your role:

   • Platform engineer: If you are rebuilding the image to update the default pipeline for your organization, you may create the directory within the location where you forked the tssc-sample-templates repository. For example, rebuild-image.
   • Developers: If you are rebuilding the image for your own use or a specific project, create a directory in a location outside the organization-wide fork of tssc-sample-templates to avoid conflicts.
   Copy to Clipboard Toggle word wrap

   mkdir rebuild-image

2. Run the following command and copy the container image URL:

   Copy to Clipboard Toggle word wrap

   more ../tssc-sample-templates/skeleton/ci/source-repo/gitlabci/.gitlab-ci.yml
   
   # Example:
   ...
   image: quay.io/redhat-appstudio/rhtap-task-runner:latest
   ...

3. Copy the existing pipeline content locally by running the following command:

   Copy to Clipboard Toggle word wrap

   podman run -v $(pwd):/pwd:z <The_url_you_copied_in_step_2> cp -r /work/rhtap /pwd 

   1

   1

   This command starts the container using the <the_url_you_copied_in_step_2> image. It then copies the pipeline files from /work/rhtap inside the container to your working directory ($(pwd)). Additionally, if you are not on a system with SELinux enabled (for example, Fedora, RHEL, pr CentOS), remove the :z option in the command to ensure compatibility.

4. Navigate to the rhtap directory and customize the pipelines tasks as required.

5. Create a Dockerfile in the rebuild-image directory and add the following content to include your changes in the container. Additionally, the base image quay.io/redhat-appstudio/rhtap-task-runner:latest is built on ubi/ubi-minimal, which provides a lightweight Universal Base Image (UBI). If you need to install additional software and dependencies, use microdnf. An example command:

   Copy to Clipboard Toggle word wrap

   FROM quay.io/redhat-appstudio/rhtap-task-runner:latest 

   1

   
   
   #Copy the updated pipeline tasks
   
   COPY ./rhtap /work/rhtap 

   2

   
   
   # Example: Install additional software (for example, git)
   RUN microdnf -y install make 

   3

   1

   Uses the existing rhtap-runner container as the starting point.

   2

   Copies the updated pipeline tasks from the local rhtap folder into the /work/rhtap directory inside the container.

   3

   Demonstrates the use of the microdnf to install additional software or dependencies.

6. Build the new container image with the following command:

   Copy to Clipboard Toggle word wrap

   podman build -f Dockerfile -t quay.io/<namespace>/<new_image_name> 

   1

   1

   -f Dockerfile specifies the Dockerfile to use for the build the container image. The -f flag allows you to explicitly point to the Dockerfile if it’s not named Dockerfile or is located in a different directory. -t quay.io/<namespace>/<new_image_name> assigns a tag (name) to the container image for easy identification.

7. Login to Quay.io and push the updated image:

   Copy to Clipboard Toggle word wrap

   podman login quay.io
   
   # Enter username and password
   
   podman push quay.io/<namespace>/<new_image_name> 

   1

   1

   This uploads the customized container image to Quay.io, making it available for use in GitLab pipelines.

8. Platform engineer only: Navigate to tssc-sample-templates > skeleton > ci > source-repo > gitlabci > .gitlab-ci.yml file and replace the container image URL with the one you just created. This makes the new container image as the default.

   Copy to Clipboard Toggle word wrap

   image: quay.io/<namespace>/<new_image_name>

9. For developers only: To update the container image just for a single repository in GitLab:

   1. Navigate to the source repository > .gitlab-ci.yaml and replace the container image URL with the one you just created.
   Copy to Clipboard Toggle word wrap

   image: quay.io/<namespace>/<new_image_name>

10. Commit and push the changes to apply the updated pipeline configuration.

1. Enable the tab for a single existing component.
2. Modify the registry detection script, and all new components will be automatically annotated correctly.

Procedure

1. In the Git repository with your component, navigate to skeleton > source-repo and open the catalog-info.yaml file.

2. Add an annotation relevant to your case:

   Copy to Clipboard Toggle word wrap

   metadata:
       annotations:
           'quay.io/repository-slug': `<ORGANIZATION>/<REPOSITORY>'

   Copy to Clipboard Toggle word wrap

   metadata:
       annotations:
           'jfrog-artifactory/image-name': '<IMAGE-NAME>'

3. Commit and push the changes to the repository.

Procedure

1. In a GitHub repository with your templates, navigate to skeleton > source-repo and open the catalog-info.yaml file.

2. Find code related to registry detection:

   Copy to Clipboard Toggle word wrap

     {%- if "quay" in values.image %}
       quay.io/repository-slug: ${{ values.repoSlug }}
   
     {%- elif "jfrog" in values.image or "artifactory" in values.image %}
       jfrog-artifactory/image-name: ${{ values.imageName }}

3. Replace "quay", "jfrog" or "artifactory" with a part of the URL of your registry.

   For example, if your Artifactory registry is called my-registry.mycompany.com, then your images names may be my-registry.mycompany.com/username/my-image. You can add my-registry.mycompany to catalog-info.yaml.