이 콘텐츠는 선택한 언어로 제공되지 않습니다.
Installing Red Hat Trusted Application Pipeline
Learn how to install Red Hat Trusted Application Pipeline in your cluster.
Abstract
Preface
Red Hat Trusted Application Pipeline (RHTAP) is not really a single product. Instead, it is a set of products that combine to form a highly automated, customizable, and secure platform for building applications.
RHTAP includes the following products:
- Advanced Cluster Security (ACS): to scan your artifacts for vulnerabilities.
- Developer Hub: a self-service portal for developers.
- OpenShift GitOps: to manage Kubernetes deployments and their infrastructure.
- OpenShift Pipelines: to enable automation and provide visibility for continuous integration and continuous delivery (CI/CD) of software.
- Quay.io: a container registry, to store your artifacts.
- Trusted Artifact Signer: to sign and validate the artifacts that RHTAP produces.
- Trusted Profile Analyzer: to deliver actionable information about your security posture.
To see exactly which versions of these products RHTAP supports, reference the compatibility and support matrix in our Release notes.
If you already have an instance of Quay.io or ACS, you can integrate it into your deployment of RHTAP.
Because a fully-operational instance of RHTAP involves all of the products listed above, installing RHTAP takes some effort. However, we have automated the vast majority of this process with an installer tool.
Be aware that the RHTAP installer is not a manager: it does not support upgrades. The installer generates your first deployment of RHTAP. After installation, you manage each product within RHTAP separately. And while the installer can be run multiple times, doing so after manually changing the configuration of a product may have unpredictable results.
Additionally, the products that the installer deploys are production ready, but they are sized for a proof of concept or a very small team. For larger teams, manual reconfiguration of the products is most likely necessary and should be done by following procedures documented for each individual product.
Before you can begin installation, you must meet the following prerequisites. Then you can complete all relevant installation steps.
Prerequisites
Installation steps
-
Installing
rhtap-cli
- Configuring GitHub for RHTAP
- (Optional) Integrating instances of ACS, Quay, or Jenkins
- Installing RHTAP in your cluster
- (Optional) Post-installation integrations
The following pages of this document explain each of those installation steps in detail. If you have the prerequisites, you are ready to start the installation process by creating a GitHub personal access token.
Chapter 1. Installing rhtap-cli
To minimize the complexity of installing RHTAP, we have created a CLI tool to automate much of the process. Follow the instructions in this procedure to utilize the rhtap-cli
tool.
Procedure
- In your web browser, navigate to the rhtap-cli releases page. Download the bundle file that is appropriate for your operating system.
In your CLI, unzip the bundle file.
$ cd ~/Downloads $ tar -xvzf rhtap-cli_<remaining file name>.tar.gz
(Optional) Move
rhtap-cli
somewhere that is on your $PATH.$ echo $PATH <output omitted>:Users/<username>/bin $ mv rhtap-cli Users/<username>/bin/.
Verification
To ensure you have successfully installed the CLI tool, run the following command. You should see the basic help output for rhtap-cli
.
$ rhtap-cli --help
Chapter 2. Configuring GitHub for RHTAP
After installation, RHTAP uses GitHub to authenticate users. RHTAP also uses GitHub as the destination for repositories that it generates.
To enable this functionality, before installing RHTAP in your cluster, you must first complete the following procedures to configure GitHub for RHTAP:
- Creating a personal access token
- Creating a GitHub application
- (Optional) Forking the software catalog
Below are the detailed instructions for each of these procedures.
2.1. Creating a GitHub personal access token
Before completing this procedure, you need to own a GitHub organization that you can use for RHTAP. This can be a new organization that you create, an organization you already have control over, or an existing organization for which you must request the appropriate permissions from the current admins. After installing RHTAP, this GitHub organization gives RHTAP users a place to automatically create git repositories for their applications.
Once you own an organization, you are ready to follow the steps in this procedure to create a personal access token. You need this token to run a command that is covered in the next procedure.
Prerequisites:
- A GitHub account
- Ownership of a GitHub organization
Procedure:
- Go to your Developer Settings page in GitHub.
- In the left panel, under Personal access tokens, select Tokens (classic).
- From the Generate new token drop down menu under the page banner, select Generate new token (classic). You may need to authenticate to continue.
- Enter a name, select an expiration date, and under Select scopes, select repo (which should automatically include all scopes from repo: status to security_events).
Select Generate token. GitHub redirects you to a new page, where your token is visible. Make sure to label and save this token somewhere in your files.
NoteIf you plan to complete any of the optional procedures, we recommend creating a file (for example,
~/install_values.txt
) where you can store all the values that those procedures generate, along with this access token.
2.2. Creating a GitHub application for RHTAP
Creating a GitHub application for RHTAP allows developers to authenticate to Red Hat Developer Hub, which is the user interface (UI) where they can use RHTAP. This GitHub application also allows RHTAP to access developer’s source code that is hosted on GitHub.
Keep in mind that you must create and install the new application in the GitHub organization that you are using for Red Hat Trusted Application Pipeline. RHTAP can subsequently create new repositories within that organization, to serve as the source code for the applications it builds. You must also be log into an OpenShift cluster, where the app credentials are stored as a Kubernetes secret.
Prerequisites
- Ownership of a GitHub organization
- A GitHub personal access token (from the previous procedure)
- ClusterAdmin access to an OpenShift cluster
Procedure
- In the web UI or your CLI, login to the OpenShift cluster where you plan to install RHTAP.
In your CLI, run the following command to start creating a GitHub application. Replace $TOKEN with the token you created in the previous procedure. Replace $ORG_NAME with the name of the GitHub organization you are using for RHTAP. Replace $APP_NAME with a name you would like to use for your application.
Replace $CONFIG with the path of the
config.yaml
file that lists the Helm charts needed to install the required RHTAP components. By default, this file is located in therhtap-cli/installer
directory.NoteYou don’t need to add the
--config
parameter if you run therhtap-cli integration
command from a local clone of the rhtap-cli repo and you’re in the corresponding branch. In this case, RHTAP locatesconfig.yaml
automatically.$ rhtap-cli integration github-app --create --token="$TOKEN" --org="$ORG_NAME" $APP_NAME --config="$CONFIG"
- A web browser window should open. In that window, click Create your GitHub App.
- The button redirects you to GitHub. If necessary, authenticate in GitHub to confirm access. Then click Create GitHub App for <your organization’s name>.
- A new message displays, telling you that the app was successfully created. Click on the hyperlinked text to install the new application in your GitHub organization.
- The link redirects you to GitHub. Click the green Install button.
- Select the organization that you are using for RHTAP.
When prompted, select All repositories, so RHTAP can create new repositories in your organization. Click the green Install button.
NoteYou may want to keep this GitHub page open, even though you can close it without interrupting installation. In the page banner, there is a link that you can use after installation to access RHTAP (beginning with
https://backstage-developer-hub-rhtap…
).
2.3. (Optional) Forking the RHTAP catalog repository
RHTAP provides users with a set of software templates that enable developers to build applications more quickly. You may want to customize these templates, to tailor them to your users' specific needs. To enable this customization, you must fork the repository that contains the default templates now. In a later stage of the installation process, you can configure RHTAP to find software templates in your customizable fork, rather than in the default repository.
Procedure:
- In your web browser, navigate to the RHTAP software catalog repository.
Beneath the banner of the page, select Fork and fork the repository.
-
Uncheck the box that says "Copy the
main
branch only".
-
Uncheck the box that says "Copy the
-
Once the fork is ready, copy its address. Label and save it in
~/install_values.txt
. In your new fork, beneath the banner, click main to open a dropdown menu. Under Tags, select the release that corresponds to the version of RHTAP that you are using.
NoteBe sure to update your fork from time to time, so updates from the upstream repository can benefit your instance of RHTAP.
Chapter 3. Integrating pre-existing deployments and outside products
RHTAP installs a network of products that work together to form a secure, automated CI/CD platform. However, two of these products you may have already installed in your cluster: Advanced Cluster Security (ACS) and Quay. If you already have instances of either of these products, you can integrate them into your installation of RHTAP. Integration saves time and prevents data loss. If you have instances of these products in your cluster and do not integrate them, then the installer just creates new instances in new namespaces.
There are three other products that RHTAP uses by default, which you can replace in your instance. The table below names these products, their purpose, and what other products you can use instead.
Product | Purpose | Possible substitutes |
---|---|---|
GitHub | Source code repository |
|
Tekton | CI pipeline |
CI pipeline substitutes conform to SLSA Build L2. Only Tekton conforms to Build L3. |
Quay | Registry for artifacts | Artifactory |
Please note that when you use alternative providers for your Git, CI and registry integrations, RHTAP also installs plugins for those products in Red Hat Developer Hub. Most of them are Technology Preview or community plugins. This means that replacing default products can introduce security risks and is not recommended for a production environment. For more information, please see the plugins table in our release notes and the RHDH documentation about plugins.
The following procedures explain how to integrate these products into RHTAP.
Examples of all rhtap-cli integration
commands listed in this guide include the --config
parameter. Replace $CONFIG with the path of the config.yaml
file.
You don’t need to add --config
if you run the rhtap-cli integration
command from a local clone of the rhtap-cli repo and you’re in the corresponding branch.
3.1. (Optional) Integrating ACS
Prerequisites
- Administrator access to an instance of ACS.
Procedure
Before you can integrate your instance of ACS, you need an API token and the central endpoint URL.
- In your CLI, login to the OpenShift cluster where you plan to install RHTAP.
Run the integration command. Replace $ENDPOINT with your ACS central endpoint URL, and $TOKEN with your ACS API token.
rhtap-cli integration acs --endpoint="$ENDPOINT" --token="$TOKEN" --config="$CONFIG"
3.2. (Optional) Integrating Quay
In this procedure, you obtain two values from your instance of Quay. Then you integrate your instance into RHTAP.
Prerequisites:
- A Quay account
- Ownership of a Quay organization (you can use any plan, including the free option).
We recommend using a robot account in Quay for this procedure. This way, once RHTAP is installed, multiple users can authenticate to your organization’s namespace in Quay.
Procedure:
- In your web browser, login to Quay. On the right side of the banner, select your username and select Account Settings from the dropdown menu.
- On your user settings page, under Docker CLI Password, select Generate Encrypted Password. In the popup window, enter your password to authenticate.
-
Next, still in the popup window, select Docker Configuration > View [username]-auth.json. Copy the string, without the quotation marks, following
"auth":
. -
In your
~/install_values.txt
file, label and create the Docker configuration value with the following format, using your username and auth token where appropriate: {"auths": {"quay.io": {"auth": "[auth token]","email": ""}}} - Back in the Quay UI, return to the default Repositories page. On the right side, under Users and Organizations, select the Quay organization you want to use for RHTAP.
- From the tabs on the left side, select Applications.
- Click Create New Application. Give your application a name.
- Click on the application’s name.
- From the tabs on the left, select Generate Token.
- From the options for permissions for the token, select View all visible repositories.
- Click Generate Access Token.
- Click Authorize Applicaiton.
-
The UI displays an access token. Label and save this token in
~/install_values.txt
, too. In your CLI, run the following command to integrate your instance of Quay. Replace $DOCKERCONFIGJSON with the Docker configuration value. Replace $API_TOKEN with the token you just generated. And replace $URL with the address for your instance of Quay (https://quay.io if you have not installed Quay in your cluster).
$ rhtap-cli integration quay --dockerconfigjson="$DOCKERCONFIGJSON" --token="$API_TOKEN" --url="$URL" --config="$CONFIG"
3.3. (Optional) Integrating GitLab
If you want to use GitLab to host your source code, or as a CI provider, complete the steps in the following procedure.
Prerequisites
- You must have the necessary permissions to create and manage GitLab jobs.
- You must have a GitLab API token.
-
You must have a host URL, if you plan to integrate with a custom GitLab host. If you do not specify a GitLab host URL, the system defaults to
gitlab.com
.
Procedure
In your CLI, run the integration command. Replace $API_TOKEN with your GitLab API token. If you are integrating with a custom GitLab host, replace $URL with you GitLab host URL. If you are using the default
gitlab.com
host, you can remove the--host
option.$ rhtap-cli integration gitlab --token="$API_TOKEN" --host="$URL" --config="$CONFIG"
3.4. (Optional) Integrating Jenkins
Prerequisites
- You must have the necessary permissions to create and manage Jenkins jobs.
- You must have a URL using which you access Jenkins, a Jenkins user ID, and an API token.
Procedure
In your CLI, run the integration command. Replace $API_TOKEN with your Jenkins API token, $URL with you Jenkins instance URL, $USERNAME with your Jenkins user ID.
$ rhtap-cli integration jenkins --token="$API_TOKEN" --url="$URL" --username="$USERNAME" --config="$CONFIG"
3.5. (Optional) Integrating JFrog Artifactory
Prerequisites
- Admin access to an instance of Artifactory
- A repository in Artifactory that you want to use with RHTAP
Procedure
- In the Artifactory UI, in the Administration view, click the green Set Up Client/CI Tool button next to the repository that you want to use.
- Select Docker Client
Follow the UI instructions to authenticate in your CLI.
-
The UI generates a token to use as a password. Make sure to save it in
~/install_values.txt
. -
When you login to JFrog in your CLI, you should get a message saying your password has been stored in a location such as
~/.docker/config.json
. If you do not see this message, a later step in this procedure explains what to do.
-
The UI generates a token to use as a password. Make sure to save it in
In your CLI, run the integration command. Set the value of ARTIFACTORY_URL to the URL of your instance (for example, "https://myusername.jfrog.io"). Set the value of ARTIFACTORY_DOCKERCONFIGJSON to the contents of the file where your password was stored. Set the value of ARTIFACTORY_API_TOKEN to the token that JFrog generated.
$ rhtap-cli integration artifactory --url="$ARTIFACTORY_URL" --dockerconfigjson="$ARTIFACTORY_DOCKERCONFIGJSON" --token="$ARTIFACTORY_API_TOKEN" --config="$CONFIG"
If your CLI did not print a message about the config.json
file, you can create its contents as follows: { "auths": { "<URL for your JFrog instance>":{ "auth": "<base64 format of username:password>", "email": "" }}}
3.6. (Optional) Integrating Bitbucket
If you want to use Bitbucket cloud to host your source code, complete the steps in the following procedure.
Prerequisites
You must have Bitbucket username. To find your username:
- On the sidebar in Bitbucket, click your profile picture and select View profile.
- In the sidebar, select Settings. The system displays your username in the account settings.
- You must have a app password.
Procedure
In your CLI, run the integration command. Replace $username with your Bitbucket username, and $appPassword with your Bitbucket access tokens. If you are integrating with a custom Bitbucket host, replace $URL with you Bitbucket host URL. If you are using the default
bitbucket.org
host, you can remove the--host
option.$ rhtap-cli integration bitbucket --username="$username" --app-password="$access_token" --host="$URL" --config="$CONFIG"
Chapter 4. Installing RHTAP in your cluster
Once you have configured GitHub, you are ready to install RHTAP in your cluster. The actual installation process is quite simple.
However, if you forked the software catalog, or if you integrated ACS or Quay, you must first customize a file called config.yaml
. This is also not difficult.
The following procedures explain how to complete both of these processes.
4.1. (Optional) Customizing config.yaml
If you forked the software catalog, or if you integrated ACS or Quay, you should customize the config.yaml
. Customizing this file ensures that the RHTAP installer reacts correctly to the work you did for those procedures.
Procedure
In your CLI, create a new directory.
$ mkdir tmp
Extract the install charts to your new directory. Replace $CONFIG with the path of the
config.yaml
file.NoteYou don’t need to add the
--config
parameter if you run therhtap-cli installer
command from a local clone of the rhtap-cli repo and you’re in the corresponding branch. In this case, RHTAP locatesconfig.yaml
automatically.$ rhtap-cli installer --extract=tmp --config="$CONFIG"
Create a copy of the
config.yaml
that now exists in that directory.$ cp tmp/config.yaml tmp/my-config.yaml
Using your preferred text editor, change the contents of the file as appropriate for the optional procedures you completed:
If you forked the software catalog, then change the
catalogURL
to the URL for your fork, as shown in the example below.redHatDeveloperHub: enabled: &rhdhEnabled true namespace: *installerNamespace properties: catalogURL: https://github.com/<your username>/tssc-sample-templates/blob/release/all.yaml
If you integrated ACS or Quay, then change the values for the relevant
enabled
fields tofalse
. The example below shows the change you need to make for ACS.redHatAdvancedClusterSecurity: enabled: false namespace: rhtap-acs
NoteIf you try to integrate ACS or Quay but do not customize
config.yaml
, RHTAP still installs and uses new instances of those products. You must customizeconfig.yaml
for yourrhtap-cli integration
commands to take effect.
-
Once you have made the appropriate changes, save the new
my-config.yaml
file.
4.2. Installing RHTAP with the rhtap-cli deploy
command
If you have configured GitHub and, if necessary, customized config.yaml
, then you are ready to install RHTAP.
Prerequisites
- You must have logged in to your OCP cluster as ClusterAdmin.
You must ensure that none of the following operators are already installed in your cluster:
- AMQ Streams
- Crunch-Data PostgreSQL
- OpenShift GitOps
- Keycloak
- OpenShift Pipelines
- Trusted Artifact Signer
- Quay
- Advanced Cluster Security
- Developer Hub
Procedure
In your CLI, run the installation command. If you did not make any changes to
config.yaml
, you can simply runrhtap-cli deploy
. But if you did customize that file, run the following command, and replace the $CONFIG variable with the path of your customized file.NoteInstallation takes about fifteen minutes to complete.
$ rhtap-cli deploy --config=$CONFIG
-
Once installation is complete, be sure to save the output of the
rhtap-cli deploy
command in your~/install_values.txt
file. This output enables you to access your instances of the new products that are now installed. Now, you can access your instance of RHTAP!
- After creating a GitHub app, you may have left the page for your new GitHub app open, as our note suggested. In that case, you can use the link in the banner of that page to access RHTAP.
-
Otherwise, navigate to your the Authorized GitHub Apps tab on your Applications page. Click on the name of the app you created for RHTAP. Again, in the banner of this page, you can find the link you need to access RHTAP, which begins with
https://backstage-developer-hub-rhtap…
.
Chapter 5. Post-installation integrations
After installing RHTAP, complete the following tasks to ensure that RHTAP works properly.
5.1. Integrating Quay into ACS (Optional)
If you are using your own Quay instance instead of Quay.io, or if you plan to use private repositories in Quay, then you must integrate Quay into ACS. This ensures ACS has access to the repositories you use in Quay.
Procedure
-
Go to your ACS instance. If you did not have ACS before installing RHTAP, you can find the access details in the
rhtap-cli deploy
command output, which you saved to~/install_values.txt
at the end of the installation procedure. - Follow the instructions in the Red Hat Advanced Cluster Security for Kubernetes 4.5 documentation to integrate Quay into ACS.
5.2. Additional integrations
If you integrated other tools into RHTAP, you must configure them so they can run the build pipelines provided by RHTAP:
If you integrated | Then |
---|---|
Bitbucket | Review the Setting up Bitbucket for security integrations documentation. |
Jenkins | Review the Setting up Jenkins for security integrations documentation. |
Revised on 2025-01-22 20:07:31 UTC