Customizing Red Hat Advanced Developer Suite - software supply chain

Procedure

1. Navigate to the cloned tssc-sample-templates repository on your local machine.

2. Open the properties file with your preferred text editor. For example, run the following command in your terminal to open it with Visual Studio Code:

   $ code properties

   # PE can replace these values with on-prem host
   export GITHUB__DEFAULT__HOST=github.com
   export GITLAB__DEFAULT__HOST=gitlab.com
   export BITBUCKET__DEFAULT__HOST=bitbucket.org
   
   export QUAY__DEFAULT__HOST=quay.io
   
   # leave empty if you don't want to set defaults for your git or quay org
   export GITHUB__DEFAULT__ORG=""
   export GITLAB__DEFAULT__ORG=""
   export BITBUCKET__DEFAULT__ORG=""
   export QUAY__DEFAULT__ORG=""
   
   # PE can replace these values with own pipeline fork
   export PIPELINE__REPO__URL=https://github.com/redhat-appstudio/tssc-sample-pipelines
   export PIPELINE__REPO__BRANCH=main
   
   export DEFAULT__DEPLOYMENT__NAMESPACE__PREFIX=tssc-app
   
   export RHTAP__DEFAULT__NAMESPACE=tssc
   export ARGOCD__DEFAULT__NAMESPACE=tssc-gitops
   export ARGOCD__DEFAULT__INSTANCE=default
   export ARGOCD__DEFAULT__PROJECT=default
   
   
   # For secret reference in Repository CRs
   # Secret will be prefixed by CI name, gitops (for github), or gitlab, or bitbucket in template
   # export GIT__SECRET__DEFAULT__NAME=auth-secret
   export GIT__SECRET__DEFAULT__KEY=password
   export WEBHOOK__SECRET__DEFAULT__NAME=pipelines-secret
   export WEBHOOK__SECRET__DEFAULT__KEY=webhook.secret
   
   # compute the template tag to set defaults, leave empty if not set
   if [ ! -z "${GITHUB__DEFAULT__ORG}" ]; then
   export DEFAULT_ORG_FOR_GITHUB="default: $GITHUB__DEFAULT__ORG"
   fi
   if [ ! -z "${GITLAB__DEFAULT__ORG}" ]; then
   export DEFAULT_ORG_FOR_GITLAB="default: $GITLAB__DEFAULT__ORG"
   fi
   if [ ! -z "${BITBUCKET__DEFAULT__ORG}" ]; then
   export DEFAULT_ORG_FOR_BITBUCKET="default: $BITBUCKET__DEFAULT__ORG"
   fi
   if [ ! -z "${QUAY__DEFAULT__ORG}" ]; then
   export DEFAULT_ORG_FOR_QUAY="default: $QUAY__DEFAULT__ORG"
   fi

3. Customize the properties file by updating the following key-value pairs according to your environment:

   Expand

   Key	Description
   export GITHUB_DEFAULT_HOST	Set this to your on-premise 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. The default value is github.com.
   export GITLAB_DEFAULT_HOST	Set this to your on-premise GitLab 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. The default value is gitlab.com.
   export DEFAULT_DEPLOYMENT_NAMESPACE_PREFIX	The namespace prefix for deployments within RHADS - SSC. The default value is tssc-app. Note Update this if you have modified the default developerHub: namespacePrefixes during the 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 target branch of the forked pipeline repository. For example, main.
   export GITHUB_DEFAULT_ORG	The name of the GitHub organization that you want to set as the default.
   export QUAY_DEFAULT_ORG	The name of the Quay organization that you want to set as the default.

   Show more

4. Adjust the software templates, replacing default host values with your specified inputs by running the following command from the top-level directory of the repository:

   $ ./generate.sh

5. For Jenkins only: To customize your Jenkins library, navigate to skeleton > ci > gitops-template > jenkins, and open the Jenkinsfile file. 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 instance is not deployed to an on-premise OpenShift Container Platform (OCP) 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 the external Jenkins server can communicate with the Rekor and TUF services installed with RHADS - SSC. Without this customization, RHADS - SSC might not sign the container images correctly in the Jenkins pipeline.

   To update the REKOR_HOST and TUF_MIRROR variables:

   1. Open the env.sh file by navigating to the skeleton > ci > gitops-template > jenkins > tssc directory.

      The second env.sh file is located at skeleton > ci > source-repo > jenkins > tssc. Update the settings to suit your needs.

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

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

   2. Replace .svc with your OCP 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 RHADS - SSC. If these data aren’t available to you, run this command in your CLI and select the Rekor and TUF routes in the output:

      $ oc get routes -n tssc-tas

      An example of a Rekor server URL: http://rekor-server.tssc-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, RHADS - SSC uses dynamically loaded Jenkins libraries. If you need to configure RHADS - SSC to use built-in Jenkins libraries instead of dynamic loading, you must modify the Jenkins provisioning setup. This change can improve traceability and Conforma attestations. For detailed instructions, see Configuring RHADS - SSC to use built-in Jenkins libraries.
6. For Red Hat Advanced Cluster Security (RHACS) only: To enable RHACS scans, set the export DISABLE_ACS to false in the env.sh file.
7. Option A: Commit and push the changes to your repository. This automatically updates the template in Red Hat Developer Hub (RHDH).

8. Option B: Manually import and refresh the templates using the following steps:

   1. Go to your forked sample template repository on your Git provider.

   2. Get the appropriate URL:

      • 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.
      • For all 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 the RHDH platform.
   4. Select Create > Register Existing Component.
   5. In the Select URL field, paste the appropriate URL that you copied in the previous step.
   6. Select Analyze and then select Import to update the templates in RHDH.

Procedure

1. Access the forked tssc-sample-pipelines repository URL:

   1. Open the forked tssc-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 tssc-sample-templates repository:

   1. In your terminal, navigate to the local clone of the tssc-sample-templates repository.

   2. Update the Tekton definition by running the following command:

      ./scripts/update-tekton-definition {fork_url} {branch_name}

      Replace {fork_url} with the copied URL from step 1 and {branch_name} with the desired branch name. For example, to update the Tekton definition, run the following command:

      $ .scripts/update-tekton-definition \https://github.com/myusername/tssc-sample-pipelines main

3. Review, commit, and push your changes:

   1. Review the updated files within the tssc-sample-templates repository.
   2. Commit the changes with an appropriate message.
   3. Push the committed changes to the 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 can 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.

     $ mkdir rebuild-image

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

   $ less ../tssc-sample-templates/skeleton/ci/source-repo/gitlabci/.gitlab-ci.yml

   image: registry.access.redhat.com/rhtap-task-runner/rhtap-task-runner-rhel9:{ProductVersion}

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

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

   This command starts the container by 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, or 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 registry.access.redhat.com/rhtap-task-runner/rhtap-task-runner-rhel9:1.7 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. For example, example command:

   FROM registry.access.redhat.com/rhtap-task-runner/rhtap-task-runner-rhel9:1.7
   
   COPY ./rhtap /work/rhtap
   
   RUN microdnf -y install make

   FROM

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

   COPY

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

   RUN

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

6. Build the new container image by running the following command:

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

   1

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

7. Login to Quay.io by running the following command:

   $ podman login quay.io

8. Push the updated image by running the following command:

   $ podman push quay.io/<namespace>/<new_image_name>

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

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

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

10. For developers only: To update the container image just for a single repository in GitLab, navigate to the source repository > .gitlab-ci.yaml and replace the container image URL with the one you just created.

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

11. 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:

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

   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:

     {%- 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.