Installing the server software on Red Hat OpenShift

You can install Rational® Test Automation Server on the Red Hat OpenShift server that has the Kubernetes Engine environment to run functional, integration, and performance tests. Rational® Test Automation Server combines test data, test environments, and test runs and reports into a single web-based browser for testers and non-testers.

Before you begin

You must have performed the following tasks:

Completed tasks provided in the Prerequisites section. See Prerequisites for installing the server software on Red Hat OpenShift.
Installed the following software:
- OpenShift CLI
- Helm
Copied the Entitlement key from the Container software library.

Procedure

Open and log in to the terminal.
Create a namespace to install the server software by running the following command:
```
oc new-project test-system
```
Remember: test-system is the name of the namespace. If you created a namespace by using a different value, then you must use that value in place of the test-system in all the instances in this procedure.
Add the entitlement registry to Helm to access the server install charts by running the following command:
```
helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm
```
Run the following command to get the latest updates from the repository:
```
helm repo update
```
Create a Secret to pull images that are used by Rational® Test Automation Server by running the following commands:
```
oc create secret docker-registry cp.icr.io \
-n test-system \
--docker-server=cp.icr.io \
--docker-username=cp \
--docker-password={your_entitlement_key} \
--docker-email=example@abc.com
```
Notes:
- You must substitute {your_entitlement_key} with the key that you copied from Container software library.
- You can replace example@abc.com with the administrator email address, if required.
Perform one of the following steps to enable certificates as trusted certificates:
1. Perform the following steps to add the Certificate Authority (CA) into a Secret:
  1. Run the following command to verify whether an additional CA is required:
```
curl -sw'%{http_code}' -o/dev/null \
"https://wildcard.$(oc get -n openshift-ingress-operator ingresscontroller default -ojsonpath='{.status.domain}')"
```
    If the result of the command is 503, the CA is already trusted. You must continue with 7.
    
    If the result of the command is 000, then CA must be added into a Secret. You must continue with 6.a.ii.
  2. Run the following command to get the default CA in a PEM format:
```
oc get -n openshift-ingress-operator secret router-ca -ojsonpath='{.data.tls\.crt}' | base64 --decode > ca.crt
```
  3. Run the following command to validate that the CA used to sign the certificate is same for ingress:
```
curl -sw'%{http_code}' -o/dev/null --cacert ca.crt \
"https://wildcard.$(oc get -n openshift-ingress-operator ingresscontroller default -ojsonpath='{.status.domain}')"
```
    The result of the command must be 503.
    
    If the result of the command is 000, then the certificate configuration has been customized. You must find the certificate of the signer to go to the next step.
  4. Run the following command to create an ingress Secret to store the CA:
```
oc create secret generic -n test-system ingress --from-file=ca.crt=ca.crt
```
2. Perform the following steps to add the Certificate Authority (CA) into a Secret if you are using OpenShift Service Mesh service virtualization, a Tech Preview feature:
  1. Run the following command to retrieve the charts:
```
helm pull --untar ibm-helm/ibm-rtas-prod --version 4.1013.0
```
  2. Run the following script from the files directory:
```
./files/certificate.sh -n istio-system -s istio-ingressgateway-certs {openshift-cluster-dns-name}
```
  3. Run the following command to create an ingress Secret:
    oc create secret generic -n test-system ingress \ "--from-literal=ca.crt=$(oc get -n istio-system secret istio-ingressgateway-certs -ojsonpath='{.data.ca\.crt}' | base64 --decode)"
  4. Run the following commands to enable an OpenShift route that the product creates for the Istio gateway:
    cat <<EOF | oc apply -n istio-system -f - >/dev/null apiVersion: maistra.io/v1 kind: ServiceMeshMemberRoll metadata: name: default spec: members: - test-system EOF
When some components such as static agents or Docker agents want to communicate with Rational® Test Automation Server, the component presents its certificate to the server to verify its identity. Rational® Test Automation Server trusts the component only if it is signed by a recognized and trusted CA. Therefore, you must add the signed CA into a trust by placing it in a Secret to enable certificates as trusted certificates.

Perform the following steps to install the server software:

You must go to step 7.c if you have completed step 6.b.

Run the following command to get the latest updates from the repository:
```
helm repo update
```
Run the following command to retrieve the charts required to install the server software:
```
helm pull --untar ibm-helm/ibm-rtas-prod --version 4.1013.0
```
Run the following commands to update the runAsUser and fsGroup to match the Security Context Constraints (SCC):
Rational® Test Automation Server is compatible with the restricted Security Context Constraint. You must run this command to ensure that the runAsUser and fsGroup strategies match with the SCC policy.
```
sed -i -e "s/runAsUser: 1001/runAsUser: $(oc get project test-system -oyaml \
  | sed -r -n 's# *openshift.io/sa.scc.uid-range: *([0-9]*)/.*#\1#p')/g;
           s/fsGroup: 1001/fsGroup: $(oc get project test-system -oyaml \
  | sed -r -n 's# *openshift.io/sa.scc.supplemental-groups: *([0-9]*)/.*#\1#p')/g" ibm-rtas-prod/values-openshift.yaml
```

Perform one of the steps described in the following table to install the server software based on your requirement:

Step description	Step no
To install the server software	Go to step 7.d.i
To install the server software and enable OpenShift Service Mesh service virtualization, a Tech Preview feature	Go to step 7.d.ii
To install the server software and enable Jaeger for performance and Web UI tests logs	Go to step 7.d.iii

Remember:

If you are upgrading from the previous version, then you must use the same value for the global.persistence.rwxStorageClass parameter that you used in the previous installation.
You can run the following command to obtain the value that you used for global.persistence.rwxStorageClass:
```
oc get pvc -n test-system data-{my-rtas}-userlibs-0 \
   -ojsonpath='{.spec.storageClassName}' && echo
```
The default certificate that terminates TLS connections, has a single wildcard. Therefore, you must prefix a single hostname segment for the global.ibmRtasIngressDomain parameter.

For example, --set global.ibmRtasIngressDomain=rtas.{dns name of the openshift cluster}

Run the following command to install the server software:

helm install {my-rtas} ./ibm-rtas-prod -n test-system \
--set license=true \
-f ibm-rtas-prod/values-openshift.yaml \
--set global.persistence.rwxStorageClass=ibmc-file-gold \
--set global.ibmRtasIngressDomain=rtas.{openshift-cluster-dns-name} \
--set global.ibmRtasPasswordAutoGenSeed={password-seed} \
--set global.ibmRtasRegistryPullSecret=cp.icr.io \
--set global.rationalLicenseKeyServer=@{rlks-ip-address}

Run the following command to install the server software and to enable OpenShift Service Mesh service virtualization, a Tech Preview feature:
```
helm install {my-rtas} ./ibm-rtas-prod -n test-system \
--set license=true \
-f ibm-rtas-prod/values-openshift.yaml \
--set global.persistence.rwxStorageClass=ibmc-file-gold \
--set global.ibmRtasIngressDomain=rtas.{openshift-cluster-dns-name} \
--set global.ibmRtasPasswordAutoGenSeed={password-seed} \
--set global.ibmRtasRegistryPullSecret=cp.icr.io \
--set global.rationalLicenseKeyServer=@{rlks-ip-address} \
-f ibm-rtas-prod/values-openshift-demo.yaml
```
Important: You must run the following command to enable service virtualization in the specific namespace:
Where, {my-rtas} is the release name that you provided during the installation of the server software.
```
oc create rolebinding istio-virtualization-enabled -n bookinfo --clusterrole={my-rtas}-execution-istio-test-system --serviceaccount=test-system:{my-rtas}-execution
```
Note: When you uninstall the chart, the manually created role bindings are not deleted from the namespace. You can run the following command to delete the role bindings:
```
oc delete rolebinding istio-virtualization-enabled -n bookinfo
```

Run the following command to install the server software and to enable Jaeger for performance and Web UI tests logs:

helm install {my-rtas} ./ibm-rtas-prod -n test-system \
--set license=true \
-f ibm-rtas-prod/values-openshift.yaml \
--set global.persistence.rwxStorageClass=ibmc-file-gold \
--set global.ibmRtasIngressDomain=rtas.{openshift-cluster-dns-name} \
--set global.ibmRtasPasswordAutoGenSeed={password-seed} \
--set global.ibmRtasRegistryPullSecret=cp.icr.io \
--set global.rationalLicenseKeyServer=@{rlks-ip-address} \
--set-string execution.annotations.sidecar\\.jaegertracing\\.io/inject=true \
--set global.jaegerAgent.enabled=true \
--set global.jaegerAgent.internalHostName=localhost \
--set global.jaegerDashboard.enabled=true \
--set global.jaegerDashboard.externalURL={my-jaeger-dashboard-url}

You must substitute the value of the variables in the helm install command with the actual value:

{my-rtas} with the release name of your choice.
Note: The release name must consist of lower case alphanumeric characters or - (hyphen), start with an alphabetic character, and end with an alphanumeric character. For example, my-org or abc-123.
{openshift-cluster-dns-name} with the ingress DNS name that you selected for the server.
Remember: You must provide the value that consists of lowercase alphanumeric characters, -(hyphen) or .(period). Also, the value must start and end with an alphanumeric character.
Note: You can run the following command to obtain the default value of openshift-cluster-dns-name:
```
oc get --namespace=openshift-ingress-operator ingresscontroller/default -ojsonpath='{.status.domain}'
```
{password-seed} with a value of your choice.

Important: This password seed is used to create several default passwords for the server. You must store the password seed securely. When you install the server software by using the backup of the user data, you can reuse the password seed. You can use this seed to restore backup files either on the current or later versions of the server software.
Optional: {rlks-ip-address} with the IP address of Rational License Key Server, if you are setting the license value for the first time.

Important: If you are upgrading the product from the previous version, you must configure the Rational License Key Server value in the License Configuration window when the installation of the server is complete.
{my-jaeger-dashboard-url} with the URL of the Jaeger server.

Optional: Run the following command to remove a job that is used to initialize the PostgresQL database during the installation of the server software:
```
oc delete job {my-rtas}-postgresql-init -n test-system
```
Optional: Perform the following steps to migrate user data into Rational® Test Automation Server, if you upgraded from the previous version:
1. Run the following script from the ibm-rtas-prod/files directory to create a directory that contains metadata related to the Persistent Volume Claims and their Persistent Volumes:
  migrate.sh create-pvcs -n test-system {my-rtas}
2. Run the following script from the ibm-rtas-prod/files directory to merge the data into the server:
  migrate.sh merge-dbs -n test-system {my-rtas}
3. Run the following command to remove the resources that were created during the migration process:
  migrate.sh delete-temp-resources -n test-system {my-rtas}
where {my-rtas} is the release name that you provided during the installation of the server software.
Run the following command to verify and test the installed server software:
```
$ helm test {my-rtas} -n test-system
```
where {my-rtas} is the release name that you provided during the installation of the server software.

Results

On successful installation of Rational® Test Automation Server, the output displays the URL to access the Rational® Test Automation Server UI.

What to do next

You can perform the following tasks:

Back up the user data that are saved in the Kubernetes clusters to secure your data. See Backing up and restoring the user data on Red Hat OpenShift.
Configure the license to use Rational® Test Automation Server. See Configuring floating licenses.