Install the Secure Tunnel Connector

Install the Secure Tunnel Connector for the network being connected to a cluster, Red Hat® OpenShift® on IBM Cloud® service (ROKS) cluster, or a host machine (VM or physical). With the Secure Tunnel Connector installed you can establish a secure tunnel between the network of the cluster where you installed the Secure Tunnel (server), such as your IBM Cloud Pak for AIOps cluster, and the cluster where you installed the Secure Tunnel Connector.

Important Depending on how you plan to create your Secure Tunnel connection, the Secure Tunnel Connector can be installed automatically. For instance, if you are connecting IBM Cloud Pak for AIOps to a Red Hat OpenShift Container Platform cluster for a ChatOps application, the Secure Tunnel Connector can be installed automatically. For more information, see Creating a Secure Tunnel connection.

Note: If your Secure Tunnel server is installed on an OpenShift cluster with a domain name that is not resolvable from DNS, then Secure Tunnel might not be able access it through the OpenShift URL. So you might find that the Tunnel Connector fails to connect to the Secure Tunnel server. You need to log in to the host machine, on which Tunnel Connector is installed, and add the IP and domain (for example, 9.30.111.xxx console-openshift-console.apps.test.cp4waiops.com ) to /etc/hosts to resolve all the domain names. Follow these steps:

Find out all the domain names to be added, run this command in the tunnel-connector-install-scripts directory

cat install-connector.sh | grep "-e SERVER=" | head -n 1

You find outputs like this:

SERVER='https://r8b74ff6d23d84fd50-cp4waiops.apps.svt-airgap-1.svt.cp4waiops.com/sre-tunnel-tunnel/ws;https://r8b74ff6d23d84fd51-cp4waiops.apps.svt-airgap-1.svt.cp4waiops.com/sre-tunnel-tunnel/ws;https://r8b74ff6d23d84fd52-cp4waiops.apps.svt-airgap-1.svt.cp4waiops.com/sre-tunnel-tunnel/ws;' \,

Add each domain in the output to the /etc/hosts with the IP address of your OpenShift cluster(for example 9.30.111.xxx r8b74ff6d23d84fd50-cp4waiops.apps.svt-airgap-1.svt.cp4waiops.com)
If you already installed Tunnel Connector before doing these steps, then you need to restart Tunnel Connector by using the command podman restart <the container id>.
If you completed the above steps and the tunnel connection console UI displays the Ready status, but your application, which is using the Secure tunnel, still does not work, check whether you added all domains to /etc/hosts.
If you selected Cloud when creating the Tunnel Connector, then you need to re-create the Tunnel Connector, select Host machine, then download the Tunnel Connector installation package and install it to a host machine.

Prerequisites

Download the Secure Tunnel Connector installation scripts:

From the console, go to Manage connections, locate the tunnel connection name, and click Action > Install Connector.
Obtain the installation package tunnel-connector-install-scripts.tar.gz by clicking Download. Or you can click Copy, and then run the copied commands on a Linux system.

Note: The installation script is for only a specific Secure Tunnel Connection, and cannot be used for other Secure Tunnel Connections.

Installing the Secure Tunnel connector to a cluster

Transfer the installation package tunnel-connector-install-scripts.tar.gz to a virtual machine where you can log in and access the cluster where you want to install the Connector.

Note: Ensure that the OpenShift oc or kubectl tool is installed in the virtual machine.
Log in to to the cluster on the virtual machine with the oc login command, and unpack the installation package.
Create the project (namespace) where you want to install the Connector.
Unpack the tunnel-connector-install-scripts.tar.gz package.
Change to the tunnel-connector-install-scripts directory.

Run the following command to install the Connector:

./install-connector.sh --namespace <namespace> --accept-license true

Verify whether the Connector is installed by running the following command:
```
oc get po -n <namespace>
```

Installing the Secure Tunnel connector to a host machine (virtual machine or physical machine)

Transfer the installation package tunnel-connector-install-scripts.tar.gz to the virtual machine where you want to install the Connector.
Log in to the virtual machine and unpack the installation package.
Install Podman on the virtual machine.

Note: Docker is not shipped or supported for Red Hat Enterprise Linux (RHEL) 8. The Podman container engine replaced docker as the preferred, maintained, and supported container runtime of choice for Red Hat Enterprise Linux 8 systems. For more information, see Running containers without Docker in the Red Hat documentation.
Unpack tunnel-connector-install-scripts.tar.gz.
Change to the tunnel-connector-install-scripts directory.
Run the ./install-connector.sh script to install the Connector on the virtual machine. Accept the license agreement when prompted to start the installation. Alternatively, you can accept the license by adding the --accept-license true parameter on the command line.
When the script finishes, verify that the Connector is installed by running the following command:
```
podman ps
```

Installing more than one Secure Tunnel Connector to a host machine

If you want to install more than one Secure Tunnel Connector:

Ensure they are from a different Secure Tunnel server or different IBM Cloud Pak for AIOps instance. If they are from the same Secure Tunnel server or IBM Cloud Pak for AIOps instance, you just need to add another ApplicationMapping to one Tunnel Connection instead of creating another Tunnel Connection and installing another Tunnel Connector.
Configure each Secure Tunnel operator to add the applicationMappingPortRang: 30000-65000 item to the YAML. The applicationMappingPortRang should be different for each Secure Tunnel. For example, the first one should be 30000-40000 and the second should be 40001-50000. Follow these steps to configure the applicationMappingPortRang:
1. From the Red Hat OpenShift Container Platform console, click Operators > Installed Operators.
2. From the Project dropdown menu, select the project in which you created the Secure Tunnel instance.
3. Click the IBM Secure Tunnel > Tunnel tab > click the existing sre-tunnel instance > change to YAML tab.
4. Add applicationMappingPortRang: 30000-65000 to the YAML and save it. The final YAML should look like:
```
spec:
  license:
    accept: true
  version: 1.0.0
  pullSecret: secure-tunnel-pull-secret
  showInContainerLog: true
  runType: production
  size: small
  controllerReplicas: 1
  applicationMappingPortRang: 30000-65000
```

The Secure Tunnel Connector container runs in the host network on host machines. Avoid port conflicts if you install multiple Secure Tunnel Connectors in the same host machine. For the following reasons, do not use port numbers 9000, 50443 or 12443

Secure Tunnel Connector container listens on port 9000 for health check by default.
The Secure Tunnel Connector container in a private network to public network connector setup connects to the Secure Tunnel server on port 50443 by default.
Secure Tunnel Connector container for Slack and Microsoft Teams listens on port 12443 on Exposed mapping port by default.
When you create a Secure Tunnel Connection from a Custom template and select Secure Tunnel in private network initializes connection to connector in public network in the Direction page, and select Host machine in the Connector settings page you must input a different port number than 50443 for your connection. And this port number must be different than the port number for all the connectors that run on the same host machine.

Figure. Port configuration
When you create a Secure Tunnel Connection from the ChatOps template, and select Host machine in the Connector settings page you must input a different port number than 50443 in the Port field and a different port number to 12443 in Exposed mapping port field. These port numbers must be different than the port numbers for all the connectors you are running on the same host machine.

Figure. Port configuration
When you complete creating the connection, you can download and transfer the installation package to the host machine on which a Secure Tunnel connector is already installed.
When you install the connector you must specify a different health check port to 9000 and the other health check ports used by other secure tunnel connectors that run on this host machine. Use this command to assign a specific <port number>,
```
./install-connector.sh --accept-license true --port <port number>
```

Note: For Port conflicts install-connector.sh uses fuser to check port conflicts during installation. If you do not have fuser installed on the host machine, install-connector.sh might miss some conflicts. If it does, your connector container might fail to start.

You can check the Secure Tunnel Connector container log by running the following command.

podman logs <container id>

where <container id> is the id of the container.

If you find a port conflict on the health check port in the container log:
1. Uninstall the container by using the command
```
./uninstall-connector.sh
```
2. Reinstall the connector with a different health check port. For example, ./install-connector.sh --accept-license true --port 9002
If you find a port conflict on the port that is used to connect the Secure Tunnel server and/or on the Exposed mapping port, then
1. Uninstall the container by using the command:
```
./uninstall-connector.sh
```
2. Delete the Secure Tunnel connection from the web UI.
3. Create a new Secure Tunnel connection with different ports and try again.

For more information, see Troubleshooting Secure Tunnel.

Optional: Uninstalling the Secure Tunnel Connector

Use the script to uninstall the Secure Tunnel Connector:

Download the Connector installation package tunnel-connector-install-scripts.tar.gz
1. From the console, go to Manage connections, locate the tunnel name.
2. Under the Action column for the tunnel, expand the menu (three dots icon) and click Install.
3. Obtain the installation package tunnel-connector-install-scripts.tar.gz by clicking Download. Or you can click Copy, and then run the copied commands on a Linux system.
  
  Note: The installation script is for only a specific Secure Tunnel Connection, and cannot be used for other Secure Tunnel Connections.
Uninstall the Connector from the Cloud with the installation package:
1. Transfer the installation package tunnel-connector-install-scripts.tar.gz to a virtual machine on which the OpenShift CLI (oc) is installed. Log in and access the Cloud where you want to uninstall the Connector.
2. Log in to the virtual machine and unpack the installation package.
3. Change to tunnel-connector-install-scripts directory
4. Run ./uninstall-connector.sh script with parameters like below to uninstall the Connector from the Cloud.
```
./uninstall-connector.sh --namespace <namespace>
```
Uninstall the Connector from the host machine with installation package:
1. Transfer the installation package tunnel-connector-install-scripts.tar.gz to the host machine on which the Connector is installed.
2. Log in to the virtual machine and unpack the installation package.
3. Change to tunnel-connector-install-scripts directory.
4. Run ./uninstall-connector.sh script with the following parameters to uninstall the Connector on the host machine.
```
./uninstall-connector.sh --namespace <namespace>
```

Optional: Delete the Secure Tunnel Connector resources after a tunnel connection is deleted

If you deleted a tunnel connection by clicking Action > Delete in the Manage connections page on the IBM Cloud Pak for AIOps console, and you did not uninstall the connector, you can delete the connector resources in the cluster virtual machine or the host machine manually. Otherwise, a new connector cannot be installed on the Cluster virtual machine or the host machine.

If the connector is running in an Red Hat OpenShift Container Platform cluster or Red Hat OpenShift on IBM Cloud, follow the steps to delete connector resources:
1. Log in to the Red Hat OpenShift Container Platform cluster or Red Hat OpenShift on IBM Cloud cluster from command line, and then find all connector resources by running the following command:
```
oc get sts,secret,service,role,route -n <your tunnel connector namespace> \
      -l app.kubernetes.io/group=<your release name>-tunnel-connector.app
```
2. You can find the release name by checking the tunnel server tunnel prefix of tunnel-network-api, like this, which gives the release name as sre-tunnel:
```
oc get deploy -n cp4aiops | grep tunnel-network-api
    sre-tunnel-tunnel-network-api                                  3/3     3            3           142m
```
3. Remove these resources by running this command:
```
for res in $(oc get sts,secret,service,role,route -n <your tunnel connector namespace> \
      -l app.kubernetes.io/group=<your release name>-tunnel-connector.app -o name )
do
oc delete -n <your tunnel connector namespace> $res
done
```
4. If there is no other Tunnel connector installed in the namespace, delete the secret by running the command:
```
oc get secret -n <your tunnel connector namespace> | grep tunnel-connector
```
  Note, Do not attempt to delete the secret if the tunnel connectors are still present as the secret might be used by one of the connectors.