Deploying the on-premises gateway in an on-premises Kubernetes or OpenShift cluster

Use your existing on-premises Kubernetes or OpenShift clusters to deploy the BMC Helix Intelligent Integrations on-premises gateway. By default, when you deploy the on-premises gateway, authentication is enabled for it.

To prepare for the deployment

1. As a tenant administrator, review the system requirements and obtain the container images and utility files.
2. As a Kubernetes or OpenShift Administrator, perform the following steps:
   1. Create a namespace.
      kubectl create ns <namespaceName>
      Example:
      kubectl create ns iionpremk8s
   2. Depending on the method you are using to access the container images, use one of the following commands to create the image pull secret for the namespace:
      • If you are planning to pull container images directly from the BMC Helix Docker Trusted Repository (DTR), use the following command:
        kubectl -n <namespaceName> create secret docker-registry dockerpull --docker-server=docker.io --docker-username=<userName> --docker-password=<passwword>
        In the above command, replace <username> and <password> with the user name and password generated when creating the Personal Access Token. For more information, see Downloading the container access key.
      • If you have set up a local Harbor registry, use the following command:
        kubectl -n <namespaceName> create secret docker-registry dockerpull --docker-server=<localHarborHost> --docker-username=<userName> --docker-password=<passwword>
        In the above command, replace <localHarborHost>, <username>, and <password> with the details of your local Harbor registry.
   3. Note the following information about the Kubernetes or OpenShift deployment:
      • namespace: Name of the Kubernetes namespace. 
      • storageclass: Name of the storage class. 
      • ingressclass: Name of the ingress class.
      • registryhost: Name of the host of the registry.
        • If you are planning to pull container images directly from the BMC Helix DTR, enter docker.io. 
        • If you have set up a local Harbor registry, enter the local Harbor registry host name.  
      • imagepullsecret: Image pull secret that you created in step 2(b).
      • imageformat: "legacy".
      • org: Name of the image registry org.
        • If you are planning to pull container images directly from the BMC Helix DTR, enter bmchelix/lpk11:. 
        • If you have set up a Harbor registry, enter the name for the image registry org according to your Harbor registry configuration. For example, HelixIIGW/IIGW01:.
      • swpuiingress, which is the ingress URL to access the on-premises gateway UI.
        For example, swpui-iionpremk8s-dev1.dsm-01.abc.com.
      • grafanaingress, which is the ingress URL to access the UI to monitor the on-premises gateway by using dashboards (Applicable for Kubernetes only).
        For example, swpgrafana-iionpremk8s-dev2.dsm-01.abc.com.

Task 1: (If you are a Helix subscriber) To deploy the on-premises gateway in an on-premises Kubernetes or OpenShift cluster

1. Copy the utility files (hii-bmc-<buildNumber>.zip) that you obtained to a temporary directory, for example, /<IIGateway_INSTALL_DIR>. 

2. Extract the utility files.
   unzip hii-bmc-<buildNumber>.zip

3. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory and open the deployment_config.json file by using a text editor. 

4. Update the following parameters:
   • namespace
   • storageclass
   • ingressclass
   • registryhost
   • imagepullsecret
   • imageformat
   • org
   • swpuiingress
   • grafanaingress
5. (Optional) Update the following parameter to configure the protocol to be used (defaults to HTTP) for authorization between the on-premises gateway and the Identity Management System (IMS), which is part of the BMC Helix platform:
   • useHttpsImsUrl
6. (Optional) If you want to deploy the on-premises gateway in high availability mode, update the following parameters:
   • useAdeStorage
   • hiigHAClusterID
   • minioAccessKey
   • minioSecretKey
   • minioServerUrl
   • minioBucketName
     For information about these parameters, see Configuring the on-premises gateway for high availability in on-premises Kubernetes and OpenShift clusters.
7. Save and close the file. 
   The following snippet shows a sample file:
   {
       "namespace": "iionpremk8s",
       "storageclass": "ceph-rbd-sc-neoceph",
       "ingressclass": "nginx",
       "registryhost": "docker.io",
       "imagepullsecret": "dockerpull",
       "imageformat": "legacy",
       "org": "bmchelixhub",
       "swpuiingress": "swpui-iionpremk8s-dev1.dsm-01.abc.com",
       "grafanaingress": "swpgrafana-iionpremk8s-dev2.dsm-01.abc.com",
       "useAdeStorage": "false",
       "hiigHAClusterID": "0",
       "minioAccessKey": "",
       "minioSecretKey": "",
       "minioServerUrl": "",
       "minioBucketName": "helix-hii-backup",
       "useHttpsImsUrl": "false"
    
8. Deploy the on-premises gateway with authentication enabled:
   1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.

   2. Run the gateway_deployment.sh script.
      ./gateway_deployment.sh

   3. Depending on your environment, enter kubernetes or openshift when prompted for the deployment method.
      The deployment_config.json file is displayed with the values that you have provided in a previous step.
   4. Enter the following information:

      • Access key and access secret key: Access key and secret key required to access the BMC Helix applications.
        For instructions about how to generate the access key and secret key, see Setting up access keys for programmatic access.

        Warning

        Important

        The keys are generated in the following format: key:<access key>::<access secret key>,tenant id: <tenant ID>. Enter <access key> and <access secret key> as the values of the access key and access secret key.

        The access key and access secret key must have the Administrators group and the Administrator role assigned.

      • Tenant Id: BMC Helix tenant ID.
        Copy the tenant ID from the access key (key:<access key>::<secret key>,tenant id: <tenant ID>).
      • Tenant URL: BMC Helix tenant URL.
      • Host name: Provide the same value as provided for the swpuiingress parameter in the deployment_config.json file.
        After you provide all the credentials, the on-premises gateway is deployed. Also, the cred.json, external.config, and nginx.config configuration files are backed up in the /<userHome>/iig_auth directory.
9. (Optional, applicable only for the deployment in the Kubernetes cluster) Perform the following steps if you plan to monitor the on-premises gateway node and container health by using dashboards:
   1. Navigate to the /<IIGateway_INSTALL_DIR>/hii/scripts directory.
   2. Run the gateway_monitoring_services_deployment.sh script:
      ./gateway_monitoring_services_deployment.sh
   3. Depending on your environment, enter kubernetes when prompted for the deployment method.
10. Perform the following steps to configure the BMC Helix destination to which you want to send data collected by BMC Helix Intelligent Integrations:

    1. Create a file with the following contents and name it ade-default-destination-min.json:

       [
         {
           "entityKind": "Destination",
           "configWithSchema": {
             "config": {
               "connection": {
         "proxyUsername": "",
                 "proxyPassword": "",
                 "accessSecretKey": "CHANGEME",
                 "allowUnsignedCertificate": false,
                 "logResponses": false,
                 "pipeLiningLimit": 1,
                 "proxyHost": "",
                 "logRequests": false,
                 "timeout": {
                   "unit": "MINUTES",
                   "value": 15
                 },
                 "proxyPort": 8888,
                 "maxResponseSize": 1000000,
                 "usesHttps": true,
                 "accessKey": "CHANGEME",
                 "port": 443,
                 "minConnections": 0,
                 "tenantId": "CHANGEME",
                 "connectingTimeout": {
                   "unit": "SECONDS",
                   "value": 30
                 },
                 "host": "CHANGEME - BMC Helix tenant host name - for example: swp-2021-1840-disceks1.abc.com",
                 "poolTimeout": {
                   "unit": "MINUTES",
                   "value": 30
                 },
                 "maxOpenRequests": 1024,
                 "maxConnections": 5,
                 "maxRedirects": 5,
                 "usesProxy": false
               },
               "poolTimeout": {
                 "unit": "MINUTES",
                 "value": 30
               }
             }
           },
           "instanceName": "BMC",
           "tenantId": "287c466d-7467-4e72-9e52-8357b4a27eaf",
           "typeName": "BmcDestination",
           "id": "CHANGEME - GENERATE NEW UUID using https://www.uuidgenerator.net/version4 e.g. 2643e089-18a8-4b0d-a58a-c022926812e0  MUST BE UNIQUE in a stack",
           "moduleId": "bmc"
         }
       ]
    2. Enter the values of the following parameters in the file:
       • proxyUsername: User name for the proxy.
       • proxyPassword: Password for the proxy.
       • proxyPort: Proxy port number.
       • proxyHost: Host name of the proxy.
       • usesProxy: Whether a proxy should be used for communication. Set its value to true or false depending on whether the proxy should be used.
         Important: If a proxy is configured for the destination, the same proxy is used for communication with the BMC Helix object storage in a high-availability deployment of the on-premises gateway. 
    3. Replace the CHANGEME value of the following parameters with the generated values: 

       • accessKeyand accessSecretKey: Access key and secret key required to access the BMC Helix applications.
         For instructions about how to generate the access key and secret key, see ​​​​​​Setting up access keys for programmatic access.

         Warning

         Important

         The keys are generated in the following format: key:<access key>::<access secret key>,tenant id: <tenant ID>. Enter <access key> and <access secret key> as the values of the access key and access secret key.

         The access key and access secret key must have the Administrators group and the Administrator role assigned.

       • tenantId(first occurrence only): BMC Helix tenant ID.
         Copy the tenant ID from the access key (key:<access key>::<secret key>,tenant id:<tenant ID>) that you generated earlier and replace the CHANGEME occurrences with the copied tenant ID.
       • host: BMC Helix tenant host name.
         For example, if the tenant URL is https://swp-2021-1840-disceks1.abc.com, replace CHANGEME with swp-2021-1840-disceks1.abc.com.
       • id: Universally unique identifier (UUID).
         Access https://www.uuidgenerator.net/version4 to generate UUID.

    4. Access the on-premises gateway UI by using the following URL:
       https://<swpuingress>/swpui
       For example, https://swpui-iionpremk8s-dev1.dsm-01.abc.com/swpui.

       Warning

       Important

       • BMC Helix Portal does not display any tile for the BMC Helix Intelligent Integrations on-premises gateway. Access the UI by using the URL specified in this step. 
       • If you encounter an issue when accessing or using BMC Helix Intelligent Integrations, see Troubleshooting the BMC Helix Intelligent Integrations issues.

    5. Import the ade-default-destination-min.json file by using the Backup/Restore option to create the destination.
       For more information, see Backing up and restoring connector configurations.

       Information

       Can I create more than one BMC destination for one instance of the on-premises gateway?

       No, BMC Helix Intelligent Integrations supports only one destination for one instance of on-premises gateway.

    6. Edit the destination connection details:
       1. On the CONNECTORS tab, click Configure Mediator on the DESTINATIONS panel.
       2. Replace the existing values in the Access Key and Access Secret Key fields with the values that you have copied in the  ade-default-destination-min.json file in step 7(c).  
       3. Click Validate to validate the connection.
       4. Click Save & Close.

Where to go from here

After you deploy the on-premises gateway, perform the following tasks:

• (Optional) If you want to ensure high availability of the on-premises gateway instances in case of any failure, see Configuring the on-premises gateway for high availability in on-premises Kubernetes and OpenShift clusters. 
• Configure connections with the required third-party products to collect data.