Chapter 2. Customizing your installation
Chapter 2. Customizing your installation The RHTAP installer deploys 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: 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 and do not integrate them, then the installer just creates new instances in new namespaces. Additionally, there are three products that you can replace with certain substitutes in your deployment of RHTAP. The table below names these products, their purpose, and what other products you can use instead. Product Purpose Possible substitutes GitHub Source code repository GitLab Bitbucket Tekton CI pipeline Jenkins GitHub Actions GitLab CI 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. Also be aware that, to customize your installation, you must run all relevant commands inside an rhtap-cli container, which is logged into your cluster as ClusterAdmin. The following procedures explain how to customize your installation of RHTAP, by integrating pre-existing instances and outside products. 2.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. Follow the instructions for the prerequisites here to create an API token. Save the token in private.env . Follow the instructions here to configure your endpoint. Save the URL in private.env . In your rhtap-cli container, run the integration command. Replace USDACS_ENDPOINT with your ACS central endpoint URL, and USDACS_TOKEN with your ACS API token. 2.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). Note 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. , still in the popup window, select Docker Configuration > View [username]-auth.json . Copy the string, without the quotation marks, following "auth": . In your private.env 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 private.env , too. In your rhtap-cli container, run the following command to integrate your instance of Quay. Replace USDQUAY_DOCKERCONFIGJSON with the Docker configuration value. Replace USDQUAY_TOKEN with the token you just generated. And replace USDQUAY_URL with the address for your instance of Quay ( https://quay.io if you have not installed Quay in your cluster). Note Make sure to put the USDQUAY_DOCKERCONFIGJSON value inside single quotes. 2.3. (Optional) Integrating Bitbucket If you want to use Bitbucket cloud to host your source code, complete the steps in the following procedure. Prerequisites A 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. An app password Procedure In your rhtap-cli container, run the integration command. Replace USDBB_USERNAME with your Bitbucket username, and USDBB_TOKEN with your Bitbucket access tokens. If you are integrating with a custom Bitbucket host, replace USDBB_URL with you Bitbucket host URL. If you are using the default bitbucket.org host, you can remove the --host option. bash-5.1USD rhtap-cli integration bitbucket --username="USDBB_USERNAME" --app-password="USDBB_TOKEN" --host="USDBB_URL" 2.4. (Optional) GitHub Actions If you want to use GitHub Actions as an alternative CI provider, you do not need to complete any additional steps before installation. The GitHub application that you already made enables this CI functionality for RHTAP. 2.5. (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 rhtap-cli container, run the integration command. Replace USDGL_API_TOKEN with your GitLab API token. If you are integrating with a custom GitLab host, replace USDGL_URL with you GitLab host URL. If you are using the default gitlab.com host, you can remove the --host option. bash-5.1USD rhtap-cli integration gitlab --token="USDGL_API_TOKEN" --host="USDGL_URL" 2.6. (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 rhtap-cli container, run the integration command. Replace USDJK_API_TOKEN with your Jenkins API token, USDJK_URL with you Jenkins instance URL, USDJK_USERNAME with your Jenkins user ID. bash-5.1USD rhtap-cli integration jenkins --token="USDJK_API_TOKEN" --url="USDJK_URL" --username="USDJK_USERNAME" 2.7. (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 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 private.env . 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. In your rhtap-cli container, run the integration command. Set the value of AF_URL to the URL of your instance (for example, "https://myusername.jfrog.io"). Set the value of AF_DOCKERCONFIGJSON to the contents of the file where your password was stored. Set the value of AF_API_TOKEN to the token that JFrog generated. bash-5.1USD rhtap-cli integration artifactory --url="USDAF_URL" --dockerconfigjson='USDAF_DOCKERCONFIGJSON' --token="USDAF_API_TOKEN" Note Make sure to put the USDAF_DOCKERCONFIGJSON value inside single quotes. Additionally, 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": "" }}}
bash-5.1USD rhtap-cli integration acs --endpoint="USDACS_ENDPOINT" --token="USDACS_TOKEN" bash-5.1USD rhtap-cli integration quay --dockerconfigjson='USDQUAY_DOCKERCONFIGJSON' --token="USDQUAY_TOKEN" --url="USDQUAY_URL" bash-5.1USD rhtap-cli integration bitbucket --username="USDBB_USERNAME" --app-password="USDBB_TOKEN" --host="USDBB_URL" bash-5.1USD rhtap-cli integration gitlab --token="USDGL_API_TOKEN" --host="USDGL_URL" bash-5.1USD rhtap-cli integration jenkins --token="USDJK_API_TOKEN" --url="USDJK_URL" --username="USDJK_USERNAME" bash-5.1USD rhtap-cli integration artifactory --url="USDAF_URL" --dockerconfigjson='USDAF_DOCKERCONFIGJSON' --token="USDAF_API_TOKEN"