Installing Secure Tunnel

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

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

Install Secure Tunnel from IBM Cloud Pak for Watson AIOps

  1. Ensure that IBM Cloud Pak for Watson AIOps is installed.

  2. An IBM Cloud Pak for Watson 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.

  3. If you want to use Secure Tunnel to integrate with Slack or Microsoft Teams, you need to create a Slack connection or a Microsoft Teams connection on the IBM Cloud Pak for Watson AIOps console. For more information, see Creating Slack connections and Microsoft Teams connections.

  4. The Secure Tunnel component is not enabled by default at IBM Cloud Pak for Watson AIOps installation time. Before you use Secure Tunnel, you need to enable the Secure Tunnel component.

    Two methods are available for enabling Secure Tunnel.

    1. Console method:

      1. Access Red Hat® OpenShift® Container Platform console.
      2. Click Operators > Installed Operators.
      3. Select IBM Cloud Pak for Watson AIOps operator, and locate the IBM Cloud Pak for Watson AIOps instance.
      4. Set Enable Secure Tunnel to true to install Secure

    2. 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 Watson AIOps instance.

      4. Select IBM Cloud Pak for Watson AIOps operator, and locate the IBM Cloud Pak for Watson AIOps instance.

      5. Click Installation Item. Switch to the YAML view, and update the YAML file by changing the enabled field of enableConnectionModule from false to true.

        spec:
  enableConnectionModule: true

        Note: If you can't find the connection and enabled fields in the YAML file, you need to add them to the YAML file manually.

        • 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 Watson AIOps namespace.

        • See the following command result:

          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

  5. (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.

  6. 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 doesn't 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 either Docker or 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 Watson AIOps (as a stand-alone component) to your OpenShift cluster

System requirements

  1. Create the catalog source with the OpenShift console

    • Log in to your Red Hat OpenShift cluster's console.

    • 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-operator-catalog
  namespace: openshift-marketplace
spec:
  displayName: ibm-operator-catalog
  publisher: IBM Content
  sourceType: grpc
  image: icr.io/cpopen/ibm-operator-catalog:latest

    • Go to Administration > Cluster Settings. Under Global Configuration > OperatorHub > Sources, verify that the ibm-operator-catalog CatalogSource object is present.

    • Note: refer to Catalog Sources

  2. Install the Secure Tunnel operator with the Red Hat OpenShift console

    • Log in to your Red Hat OpenShift cluster's console.
    • Click Operators > OperatorHub. The OperatorHub page is displayed.
    • In the All Items field, enter IBM Secure Tunnel. The Secure Tunnel operator is displayed.
    • Click the IBM Secure Tunnel tile. The IBM Secure Tunnel window is displayed.
    • Click Install. The Install Operator page is displayed.
    • Enter the following values:
      • Set the Installation mode to All namespaces on the cluster(default).
      • Set Update Channel to v4.1.
      • Set Approval Strategy to Automatic.
    • Click Install and wait for the Secure Tunnel operator to install.
    • Verify that the IBM Cloud Pak for Watson AIOps operator is successfully installed.
      • 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.

  3. Install Secure Tunnel

    • 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: Refer to 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:
      • 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.
      • In the Entitlement key section, select Copy key to copy the entitlement key to the clipboard.
      • From your Red Hat OpenShift console, click Workloads > Secrets.
      • From the Project menu, select the project that you created earlier in Create a Secure Tunnel project (namespace).
      • 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: refer to 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 dropdown 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.

          Tunnel settings:

          Parameter Description Default value Syntax
          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 docker images. secure-tunnel-pull-secret String
          runAsStandAlone If you want to install the Secure tunnel without 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: :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 OCP 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.

  4. Access the Secure Tunnel console:

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

Uninstalling Secure Tunnel

  1. If the Secure Tunnel was installed from IBM Cloud Pak for Watson AIOps, you take the following steps to disable it.

    • From your Red Hat OpenShift console, click Operators > Installed Operators.

    • From the Project menu, select the project where you created the IBM Cloud Pak for Watson AIOps instance.

    • Select the **IBM Cloud Pak for Watson AIOps operator, and locate the IBM Cloud Pak for Watson AIOps instance.

    • Click Installation Item. Switch to the YAML view, and update the YAML file by changing the enableConnectionModule field of connection from true to false.

      spec:
  enableConnectionModule: false
  2. If the Secure Tunnel was installed from the Operator hub as stand-alone, take the following steps to uninstall it.
    • From your Red Hat OpenShift console, click Operators > Installed Operators.
    • From the Project menu, select the project where you installed the IBM Secure Tunnel.
    • Select IBM Secure Tunnel operator, and locate the Tunnel instance.
    • Delete the sre-tunnel (by default) instance of the Tunnels.
    • 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.