Installing Secure Tunnel

Use the following instructions to help you install Secure Tunnel for use with IBM Cloud Pak for AIOps.

Two methods are avilable to activate Secure Tunnel for use with IBM Cloud Pak for AIOps:

Install Secure Tunnel from IBM Cloud Pak for AIOps
Install Secure Tunnel without IBM Cloud Pak for AIOps (as a stand-alone component) to your Red Hat OpenShift cluster

Install Secure Tunnel from IBM Cloud Pak for AIOps

Ensure that IBM Cloud Pak for AIOps is installed.
An IBM Cloud Pak for AIOps console user with the Automation Administrator or Administrator role is needed to use Secure Tunnel. For more information about users and roles, see Managing user access control.
If you want to use Secure Tunnel to integrate with Slack or Microsoft Teams, you need to create a Slack integration or a Microsoft Teams integration on the IBM Cloud Pak for AIOps console. For more information, see Creating Slack integrations and Microsoft Teams integrations.
The Secure Tunnel component is not enabled by default at IBM Cloud Pak for AIOps installation time. Before you use Secure Tunnel, you need to enable the Secure Tunnel component.

Two methods are available for enabling Secure Tunnel.
- Console method:
  1. Access Red Hat® OpenShift® Container Platform console.
  2. Click Operators > Installed Operators.
  3. Select IBM Cloud Pak for AIOps operator, and locate the IBM Cloud Pak for AIOps instance.
  4. Set Enable Secure Tunnel to true to install Secure
- YAML method:
  1. Access Red Hat® OpenShift® Container Platform console.
  2. From your Red Hat OpenShift console, click Operators > Installed Operators.
  3. From the Project menu, select the project where you created the IBM Cloud Pak for AIOps instance.
  4. Select IBM Cloud Pak for AIOps operator, and locate the IBM Cloud Pak for AIOps instance.
  5. Click Installation Item. Switch to the YAML view, and update the YAML file by changing the field of enableConnectionModule from false to true.
```
spec:
  enableConnectionModule: true
```
    Note: If you cannot find the connection and enabled fields in the YAML file, you need to add them to the YAML file manually.
  6. Ensure that all Secure Tunnel pods are in running state by running the following command:
```
oc -n <namespace> get pod | grep tunnel
```
    Where <namespace> is the IBM Cloud Pak for AIOps namespace.
    
    The command result can resemble the following example:
```
NAME                                               READY   STATUS    RESTARTS   AGE
ibm-secure-tunnel-operator-677c7b4b7-gqjbg         1/1     Running   0          150m
sre-tunnel-controller-7b9d59957b-rkxp7             1/1     Running   0          147m
sre-tunnel-tunnel-network-api-985df588c-z6m4z      1/1     Running   0          147m
sre-tunnel-tunnel-ui-mcmtunnelui-56c744598-qhlfw   1/1     Running   0          147m
```
(Optional) Enable EgressNetworkPolicy: There is no egress firewall policy defined when you install Secure Tunnel, so outgoing traffic from workload pods to the internal and external network is unrestricted. If you require a more secure environment, complete the following steps:
1. Go to your OpenShift console > Operators > Installed Operators > IBM Secure Tunnel > Tunnel > sre-tunnel > YAML.
2. Add the following configuration to the YAML of the Tunnel CR to enable the egress NetworkPolicy:
```
spec:
  enableEgressNetworkPolicy: true
  ...
```
  Note: This feature only supports Red Hat OpenShift Container Platform version 4.10 and above, and ensures there are not any restrictive EgressNetworkPolicies in place.
The Secure Tunnel Connector can be installed to both a cluster (OpenShift or IBM Kubernetes Service cluster) or a host machine (virtual machine or physical machine). Depending on which method you use, make the following preparations.
- If you want to install the Connector in a cluster (OpenShift or IBM Kubernetes Service cluster):
  - Ensure that the following minimum resource requirements are met:
    - 1 vCPU
    - 1 GB random access memory (RAM)
  - Ensure that you can access the cluster from a public network. The cluster domain name needs to be resolved by a public DNS.
  - Ensure that the cluster has a CA-signed TLS certificate so that the verification handshake of the Slack server or the Microsoft Teams server can be successful. A self-signed TLS certificate does not work for a Slack connection.
- If you want to install the Connector in a host machine (virtual machine or physical machine):
  - Ensure that the following minimum resource requirements are met:
    - 1 CPU
    - 1 GB random access memory (RAM)
  - Ensure that Podman is installed, and running on the virtual machine or physical machine.
  - If this is used to integrate with the Slack or MS Teams. You need to meet the following extra conditions:
    - Ensure that you can access the host machine from a public network. The hostname needs to be resolved by a public DNS.
    - Ensure that a CA-signed TLS certificate is available. This is used when you create the ChatOps connection.
      
      Note: If you have an IBM Cloud account, see Getting started with IBM Cloud Internet Services to apply for a DNS name, and see Preparing to order public certificates to apply for a CA-signed certificate. Extract the CA-signed certificate file, hostname.pem, for the certificate and hostname.key for the private key. If an intermediate file is in your CA-signed certificate file – such as hostname-intermediate.pem – concatenate this file with a cert file, such as hostname.pem, by running the following command:
```
cat hostname-intermediate.pem >> hostname.pem
```

Install Secure Tunnel without IBM Cloud Pak for AIOps (as a stand-alone component) to your OpenShift cluster

Ensure that your cluster meets the following requirements:
- Supported Red Hat OpenShift Container Platform versions
- Hardware requirements: Ensure that the following minimum resource requirements are met:
  - 2 vCPU
  - 2 GB random access memory (RAM)
Create the catalog source with the OpenShift console
1. Log in to your Red Hat OpenShift cluster's console.
2. Add the IBM Operators CatalogSource. Click the plus icon in the upper right corner to open the Import YAML dialog box. Paste in the following content, and then click Create:
```
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: ibm-aiops-catalog
  namespace: openshift-marketplace
spec:
  displayName: ibm-aiops-catalog
  publisher: IBM Content
  sourceType: grpc
  image: icr.io/cpopen/ibm-aiops-catalog@sha256:58c0082ad5e9de6bc2869b528e847702f6c183a06ac49a82d64ad8efd339f753
```
3. Go to Administration > Cluster Settings. Under Global Configuration > OperatorHub > Sources, verify that the ibm-aiops-catalog CatalogSource object is present.
  
  Note: For more information, see Catalog Sources
Install the Secure Tunnel operator with the Red Hat OpenShift console
1. Log in to your Red Hat OpenShift cluster's console.
2. Click Operators > OperatorHub. The OperatorHub page is displayed.
3. In the All Items field, enter IBM Secure Tunnel. The Secure Tunnel operator is displayed.
4. Click the IBM Secure Tunnel tile. The IBM Secure Tunnel window is displayed.
5. Click Install. The Install Operator page is displayed.
6. Enter the following values:
  1. Set the Installation mode to All namespaces on the cluster(default).
  2. Set Update Channel to v4.8.
  3. Set Approval Strategy to Automatic.
7. Click Install and wait for the Secure Tunnel operator to install.
8. Verify that the IBM Cloud Pak for AIOps operator is successfully installed.
  1. Navigate to Operators > Installed Operators, and select your project from the Projects dropdown. Secure Tunnel operator in the project is listed with a status of Succeeded.

Install Secure Tunnel

To create a Secure Tunnel project (namespace) with the Red Hat OpenShift console From your Red Hat OpenShift console, click Home > Projects. Select Create Project, specify the name of the project that you want to create (for example tunnel-stand-alone) and click Create.

Note: For more information, see Namespace.
Create the entitlement key secret with the Red Hat OpenShift console. Complete the following steps to create a docker-registry secret to enable your deployment to pull the Secure Tunnel images from the IBM® Entitled Registry:
1. Obtain the entitlement key that is assigned to your IBMid. Log in to MyIBM Container Software Library with the IBMid and password details that are associated with the entitled software.
2. In the Entitlement key section, select Copy key to copy the entitlement key to the clipboard.
3. From your Red Hat OpenShift console, click Workloads > Secrets.
4. From the Project menu, select the project that you created earlier in Create a Secure Tunnel project (namespace).
5. Click the Create button, and select Image Pull Secret from the menu. The Create Image Pull Secret form is displayed. Enter the following values and then click Create.
  - Secret Name: secure-tunnel-pull-secret
  - Authentication Type: Image Registry Credentials
  - Registry Server Address: cp.icr.io
  - Username: cp
  - Password: Use the entitlement key that you copied earlier.
  Note: For more information, see Entitlement Keys

Create an instance of the Secure Tunnel with the Red Hat OpenShift console. Secure Tunnel is supported by namespace isolation, so you can create multiple Secure Tunnel instances in different namespaces, for different users. Secure Tunnel also uses the Red Hat OpenShift OAuth&RBAC for authentication and authorization. You can configure the permissions for each Secure Tunnel instance user.

From your Red Hat OpenShift console, click Operators > Installed Operators.
From the Project menu, select the project that you want to create the Secure Tunnel instance in. Use the project that you created earlier in Create a Secure Tunnel project (namespace).
Select IBM Secure Tunnel operator.

Click Create Installation on the Tunnel box. The default Form View is displayed. Enter the following values:

Name: Specify the name that you want your Secure Tunnel instance to be called.
License: Expand the License section and read the agreement. Toggle the License Acceptance switch to True to accept the license.
Image Pull Secret: Select the secure-tunnel-pull-secret secret that you created in the step Create the entitlement key secret.
runAsStandAlone: If the IBM Certificate manager is not installed in your environment. Toggle this switch to True and it will create the TLS Certificate that is used by the Secure Tunnel without the IBM Certificate manager.
Size: Select the size that you require for your Secure Tunnel installation.
Audit Receiver: Refer to the audit log guide
(Optional) Enable EgressNetworkPolicy: There is no egress firewall policy defined when you install Secure Tunnel, so outgoing traffic from workload pods to the internal and external network is unrestricted. If you require a more secure environment, toggle this switch to True to enable the egress NetworkPolicy. *Note: This feature only supports Red Hat OpenShift Container Platform version 4.10 and above, and ensures there are not any restrictive EgressNetworkPolicies in place.

Refer below to the tunnel parameters with their description, variable type and default values.

Tunnel Settings
Parameter	Description	Default value	Type
size	The sizing of the Secure Tunnel. Supported values: `small`, `medium`, `large`. `small`: replica is 1 for all operands, no HA; `medium`: replica is 3 with HA enabled; `large`: replica is 3 with HA enabled and with extra capacity for CPU/memory.	small	String
license.accept	Expand the License section and read the agreement. Toggle the License Acceptance switch to True to accept the license.	false	Boolean
uiReplicas	The replicas of the UI server pods.	Depends on size	int
apiReplicas	The replicas of the API server pods.	Depends on size	int
controllerReplicas	The replicas of the controller server pods.	Depends on size	int
workerReplicas	The replicas of the worker server pods per tunnel connection.	Depends on size	int
pullSecret	The pull secret of the Secure Tunnel images.	secure-tunnel-pull-secret	String
runAsStandAlone	If you want to install the Secure tunnel without IBM Cloud Pak for AIOps, toggle this to True	false	Boolean
showInContainerLog	Show audit logs in the container log.	true	Boolean
auditReceiver.mongoDB.mongoAddress.name	The name of the audit log MongoDB receiver.	null	String
auditReceiver.mongoDB.mongoAddress.mongoAddress	The audit log MongoDB receiver address. Example: `<IP>:27017`	null	String
auditReceiver.mongoDB.mongoAddress.passwordSecretName	The Kubernetes secret that contains the audit log MongoDB receiver login username and password. Create it in the Secure Tunnel namespace. It should contain "user" and "password" data items.	null	String
auditReceiver.mongoDB.mongoAddress.mongoDatabaseName	The database name of the audit log MongoDB receiver	null	String
auditReceiver.mongoDB.mongoAddress.tlsSecret The tls Kubernetes secret name of the audit log MongoDB receiver. Create it in the Secure Tunnel namespace. It should contain "ca.crt", "tls.crt" and "tls.key".	null	String
auditReceiver.syslog.name	The name of the audit log Syslog receiver.	null	String
auditReceiver.syslog.syslogAddress	The server address of the audit log Syslog receiver.	null	String
defaultTunnelWorkerResources.limits.cpu	The default Tunnel Worker cpu limit.	3000m	String
defaultTunnelWorkerResources.limits.memory	The default Tunnel Worker memory limit.	3072Mi	String
defaultTunnelWorkerResources.requests.cpu	The default Tunnel Worker cpu requests.	100m	String
defaultTunnelWorkerResources.requests.memory	The default Tunnel Worker memory requests.	128Mi String
applicationMappingPortRang	Application Mapping listen port range. For example: 30000-65000	30000-65000	String
enableEgressNetworkPolicy	If you require a more secure Secure Tunnel environment you can enable this item. Then it will create the egress network policy automatically. Note: This only works on Red Hat OpenShift 4.10 or later.	false	Boolean
connectionTLSCertDurationTime	By default, the TLS certificate that is used by the Tunnel connection. Duration time is 87600h0m0s(10 years). Update this item if you want to change the duration time.	87600h0m0s(10 years)	String

Click Create. This creates the Secure Tunnel instance.
After a few minutes, select the project that you specified for your Secure Tunnel instance from the Project menu. Navigate to Operators > Installed Operators > IBM Secure Tunnel and then click the Tunnel tab. Under Installations, look for the entry with the name that you specified for your Secure Tunnel instance, and verify that it has a Status of Phase: Running.
Refer to: Production installation

Note: One project(namespace) can only create one Secure Tunnel instance.

Access the Secure Tunnel console:
1. From your Red Hat OpenShift console, click Networking > Routes.
2. From the Project menu, select the project where you created the Secure Tunnel instance.
3. Select the sre-tunnel-tunnel-ui.
4. Click the url of the Location. The Secure Tunnel console opens. Log in with your Red Hat OpenShift Username and password.

Uninstalling Secure Tunnel

If the Secure Tunnel was installed from IBM Cloud Pak for AIOps, complete the following steps to disable it.
1. From your Red Hat OpenShift console, click Operators > Installed Operators.
2. From the Project menu, select the project where you created the IBM Cloud Pak for AIOps instance.
3. Select the **IBM Cloud Pak for AIOps operator, and locate the IBM Cloud Pak for AIOps instance.
4. Click Installation Item. Switch to the YAML view, and update the YAML file by changing the enableConnectionModule value for the connection from true to false.
```
spec:
  enableConnectionModule: false
```
If the Secure Tunnel was installed from the Operator hub as stand-alone, complete the following steps to uninstall it.
1. From your Red Hat OpenShift console, click Operators > Installed Operators.
2. From the Project menu, select the project where you installed the IBM Secure Tunnel.
3. Select IBM Secure Tunnel operator, and locate the Tunnel instance.
4. Delete the sre-tunnel (by default) instance of the Tunnels.
5. Uninstall the IBM Secure Tunnel operator from Operators > Installed Operators.

Note: There can be some resources, such as the CRDs and TLS cert secret of the secure tunnel that will not be deleted. If you want to completely clear them, you can download the uninstall-secure-tunnel.sh and run command ./uninstall-secure-tunnel.sh -n <the namespace of the secure tunnel> to do that.