This documentation supports an earlier version of BMC Helix IT Service Management on-premises deployment.To view the documentation for the latest version, select 23.3.04 from the Product version picker.

Installing BMC Helix Platform Common Services 23.4.00

BMC Helix Platform Common Services is a microservices-based platform that provides foundational services (such as user management, tenant management, and single sign-on) and the data lake (such as Elasticsearch, PostgreSQL, and MinIO).

BMC Helix Platform Common Services installation is a pre-requisite for BMC Helix Service Management 22.1.06 installation. 

Important

If you are performing a combined deployment of BMC Helix Service Management and BMC Helix IT Operations Management, and have installed BMC Helix IT Operations Management, do not install BMC Helix Platform Common Services again.

BMC Helix Platform Common Services are deployed with the BMC Helix IT Operations Management deployment.


Related topics

System-requirements

Installing

The following video (3:23) provides a summary of installing BMC Helix Platform Common Services:

icon_play.pnghttps://youtu.be/Vd5HG7txsdg

Before you begin

  • Make sure that you have created a namespace to install BMC Helix Platform Common services.

  • Verify that nothing is installed in the namespace by using the following command:

    kubectl get all -n <namespace>
  • Make sure that you have configured the nginx-configuration configmap.
    For information about the nginx-configuration configmap parameter value requirements, see System-requirements.
  • Make sure that you have permission to create ServiceAccount, Role, and RoleBinding in the BMC Helix Platform namespace.
    If you do not have permission, create a Service account, Role, and RoleBinding.


Important

Do not perform these tasks if you have already installed BMC Helix IT Operations Management (ITOM).

To create ServiceAccount, Role, and RoleBinding

To install BMC Helix Platform Common Services, you must have permission to create ServiceAccount, Role, and RoleBinding in the BMC Helix Platform namespace.

If you do not have permission, an administrator must perform the following steps to create a Service account, Role, and RoleBinding to enable you to install BMC Helix Platform Common Services:

  1. In the commons/yaml_files/serviceAccount.yaml and commons/yaml_files/role_rolebinding.yaml file replace the following values:
    1. __SERVICE_ACCOUNT__ with the name of the service account that you want to create.
    2. __NAMESPACE__ with the BMC Helix Platform namespace.

  2. To create a service account, run the following command:

    kubectl apply -f serviceAccount.yaml

  3. To create role and rolebinding, run the following command:

    kubectl apply -f role_rolebinding.yaml
  4. When you set the CUSTOM_SERVICEACCOUNT_NAME parameter in the infra.config file, replace helix-onprem-sa value with the service account name that you created.

Important

The uninstallation script deletes the custom service account.

If you have created a custom service account, after performing an uninstallation, you must recreate the custom service account.

Task 1: To download and extract the deployment manager

  1. Log in to the controller or bastion machine from where the Kubernetes cluster is accessible.
  2. Download the deployment manager helix-on-prem-deployment-manager-23.4.00.sh from BMC Electronic Product Distribution (EPD) and extract it, if you haven't already.
  3. Download the helix-on-prem-deployment-manager-hotfix-23.4.00.001.tar.gz hotfix.
    The Proactive problem management (PPM) module of BMC Helix ITSM Insights is unavailable if you use BMC Helix Service Management version 22.1.06 with BMC Helix Platform Common Services version 23.4.00 on an SSL-enabled restricted environment. The hotfix helix-on-prem-deployment-manager-hotfix-23.4.00.001.tar.gz contains a fix for this issue.
    To download the files from EPD, see Downloading-the-installation-files.
  4. Go to the directory where you downloaded the deployment manager from the EPD and give the execute permission to the helix-on-prem-deployment-manager-23.2.02.sh file.

  5. Self-extract the deployment manager. Run the following command:

    ./helix-on-prem-deployment-manager-23.2.02.sh
    cd helix-on-prem-deployment-manager

Task 2: To prepare for password encryption

  1. Go to the commons/certs directory and open the secrets.txt file.

  2. Add the following passwords to this file:

    Property

    Description

    Example

    IMAGE_REGISTRY_PASSWORD

    Password for the Docker registry.

    5016adc4-993f-4fc5-8fb0-8ef6b02ca9d3

    SMTP_PASSWORD

    Password to connect to the SMTP server. 

    In the configs/infra.config file, if the value of the SMTP_AUTH parameter file is NONE, leave the SMTP_PASSWORD value blank as shown below:

     SMTP_PASSWORD=""

    password123

    SMART_SYSTEM_PASSWORD

    Password to connect to the  BMC Discovery appliance.

    password123

    PG_PASSWD

    Password to connect to the PostgreSQL database.

    password123

    KIBANA_PASSWORD

    Password to connect to BMC Helix Logging (EFK).

    kibana123

    MINIO_ACCESS_KEY

    Password to access MinIO.

    admin

    MINIO_SECRET_KEY

    Password to connect to MinIO.

    bmcAdm1n

    ES_JKS_PASSWORD

    Password to connect to Elasticsearch.

    Important:

    • If you are using a custom CA certificate, specify the password, else specify the value as ES_JKS_PASSWORD=""
    • This password must have minimum seven characters.

    ""

  3. Save the secrets.txt file

    Troubleshooting tip

    Make sure that you provide all passwords in the secrets.txt file. Even if a single password is not added in the secrets.txt file, the deployment fails with an error.

    Sample secrets.txt file

    # cat commons/certs/secrets.txt
    #Please put the passwords in this file
    IMAGE_REGISTRY_PASSWORD=password123
    SMTP_PASSWORD=""
    SMART_SYSTEM_PASSWORD=password123
    PG_PASSWD=pGtest2020
    KIBANA_PASSWORD=kibana123MINIO_ACCESS_KEY=adminMINIO_SECRET_KEY=bmcAdm1nES_JKS_PASSWORD=test@1234

    ################## End OF THE FILE ####################

Task 3: To install BMC Helix Platform Common Services

  1. In the helix-on-prem-deployment-manager/configs/infra.config file, modify the following parameters that are environment-specific.

    Important

    • The following load balancer hosts are required. You do not need any subdomains.
      • LB_HOST
        Ensure that the LB_HOST value is not the same as the tenant URL.
      • TMS_LB_HOST
      • MINIO_LB_HOST
      • MINIO_API_LB_HOST
      • KIBANA_LB_HOST
      • Tenant URL that is derived based on the following parameters from the infra.config file:
        $COMPANY_NAME-$TENANT_TYPE-$ENVIRONMENT.$DOMAIN
    • Make sure that you have created a storage class.
      BMC supports a Bring-Your-Own-Storage-Class model, for any block storage supporting high performance IOPS. NFS is not supported for persistent volumes. CephRBD is certified by BMC.

  2. In the helix-on-prem-deployment-manager/configs/deployment.config file, modify the following parameters:

    Parameter

    Required value

    Infra services options

    DEPLOYMENT_SIZE

    itsmcompact or itsmsmall

    If you are installing BMC Helix Platform Common Service in a nonproduction environment, specify the value as itsmcompact.

    If you are installing BMC Helix Platform Common Service in a production environment, specify the value as itsmsmall.

    BMC Helix Service Managementdoes not require BMC Helix Platform Common Services resources with deployment sizes such as medium or large. To optimize resources, the deployment sizes, itsmcompact and itsmsmall, are provided for BMC Helix Service Management installation. The itsmcompact size does not support high availability. Use itsmcompact for nonproduction environments. The itsmsmall size supports high availability, so use this size for production environments.

    INFRA
    yes
    _PTPOSTGRESS
    yes
    _KAFKA
    yes
    _REDIS
    yes
    _RSSO
    yes
    _ELASTICSEARCH
    yes
    _VICTORIAMETRICS
    yes

    Important: If you are not using BMC Helix ITSM Insights, set this parameter to No.

    _MINIO
    yes

    BMC Helix Dashboard services

    HELIX_DASHBOARD_SERVICES
    yes

    BMC Helix ITSM Insights

    (Optional)ITSMINSIGHT_SERVICES

    yes 

    If you are not using BMC Helix ITSM Insights, set the ITSMINSIGHT_SERVICES and _VICTORIAMETRICS parameter values to No.

    AR System services

    ARSERVICES
    yes

    Important: Make sure that you specify the value as yes. This option registers the BMC Helix Innovation Suite services in BMC Helix Platform.

    BMC Helix Logging

    BMC_HELIX_LOGGING
    yes

  3. Install the product by running the following command:

    ./deployment-manager.sh

After the BMC Helix Platform Common Service are deployed, the tenant administrator receives the following emails:

  • An email with details about the BMC Helix Platform account
  • An email to change the BMC Helix Platform account password at the first login

All installation logs are located in the following directory:

helix-on-prem-deployment-manager/logs

To apply the hotfix

The Proactive problem management (PPM) module of BMC Helix ITSM Insights is unavailable with BMC Helix Platform Common Services version 23.4.00 on an SSL-enabled restricted environment. To resolve this issue, you must apply the helix-on-prem-deployment-manager-hotfix-23.4.00.001.tar.gz hotfix.

If you are using a local repository for synchronizing your images with BMC DTR, make sure your local image repository has the following images:

  • bmc.com/bmc/lp0lz:aif-core-service-f0261352-490
  • bmc.com/bmc/lp0lz:aif-clustering-job-86b0d26-3847
  • bmc.com/bmc/lp0lz:aif-job-manager-service-0f16b53-442

Perform the following steps to apply the hotfix:

  1. Log in to the controller from where the Kubernetes cluster is accessible.

  1. To add permissions to get, list, watch, update, and patch the deployments aif-job-manager-service and aif-core-service, run the following command:

    kubectl -n <namespace> patch role <CUSTOM_SERVICEACCOUNT_NAME>-role --type='json' -p='[{"op": "add", "path": "/rules/5/resourceNames/0", "value": "tas" }]'

    kubectl -n <namespace> patch role <CUSTOM_SERVICEACCOUNT_NAME>-role --type='json' -p='[{"op": "add", "path": "/rules/5/resourceNames/1", "value": "aif-job-manager-service" }]'

    kubectl -n <namespace> patch role <CUSTOM_SERVICEACCOUNT_NAME>-role --type='json' -p='[{"op": "add", "path": "/rules/5/resourceNames/2", "value": "aif-core-service" }]'

    Role name (<CUSTOM_SERVICEACCOUNT_NAME>) is the value that you set for the parameter CUSTOM_SERVICEACCOUNT_NAME in the configs/infra.config file.

  2. To verify that the role is updated, run the following command: 

    kubectl -n <BMC Helix Platform namespace> get role <CUSTOM_SERVICEACCOUNT_NAME>-role -o jsonpath={.rules[5]}

    Sample output:

    - apiGroups:
     - apps
      resourceNames:
     - tas
     - aif-job-manager-service            <<<< this line should be present after patching the role.
     - aif-core-service                   <<<< this line should be present after patching the role.
      resources:
     - deployments
      verbs:
     - get
     - list
     - watch
     - update
     - patch
    ~~~

  3. Extract the helix-on-prem-deployment-manager-hotfix-23.4.00.001.tar.gz to the workspace folder of 23.4.00, run the following command:

    tar xvf helix-on-prem-deployment-manager-hotfix-23.4.00.001.tar.gz 3.  

  4. Run the hotfix script hf_script.sh:

    bash hf_script.sh < full path of the 23.4.00 platform common services directory >/helix-on-prem-deployment-manager

    For example:

    bash hf_script.sh /data/23.4.00/helix-on-prem-deployment-manager

    A copy of the directory helix-on-prem-deployment-manager gets created in the same path. In the example, a new directory /data/23.4.00/helix-on-prem-deployment-manager_HF1.YYYYMMDDHHMMSS gets created.

    No changes are made to the original directory passed as a command line parameter.

Sample configuration files

Sample infra.config file
#Docker registry details
#IMAGE_REGISTRY_HOST=containers.bmc.com
#IMAGE_REGISTRY_USERNAME=<user name to access registry>
IMAGE_REGISTRY_HOST=
IMAGE_REGISTRY_USERNAME=

# keep double quotes in all variables if not required, don't leave them blank or empty
#Infra details
#NAMESPACE=dark-helmet
#LB_HOST=host-india-app.mydomain.com
#LB_PORT=443
#TMS_LB_HOST=tms-private-poc.mydomain.com
#DOMAIN=mydomain.com
#MINIO_LB_HOST=minio-private-poc.mydomain.com
#KIBANA_LB_HOST=kibana-private-poc.mydomain.com
#ENVIRONMENT=<Type of environment>
# The values of ENVIRONMENT is based on kind of setup you are going to create e.g. dev, qa, production, poc, multi-service, canary etc. (this is not based on deployment size compact, small, medium, large etc)
ENVIRONMENT=dev
NAMESPACE=
LB_HOST=
LB_PORT=
TMS_LB_HOST=
DOMAIN=
# If minio web access required .Please give LB (e.g.minio.domain.com )which has DNS entry otherwise keep blank "".
MINIO_LB_HOST=
# Use minio api ingress(minio-api.domain.com)
MINIO_API_LB_HOST=
KIBANA_LB_HOST=

#Cluster type can have values openshift or ocp for OpenShift.
#If CLUSTER_TYPE is not set to openshift or ocp then cluster type is treated as kubernetes cluster.
CLUSTER_TYPE=

#Tenant details for onboarding
#COMPANY_NAME=<tenant company name same as in tenant discover appliance url>
#TENANT_EMAIL=<tenant email address>
#TENANT_FIRST_NAME=<tenant first name>
#TENANT_LAST_NAME=<tenant last name>
## TENANT_TYPE= <Tenant type in tenant url same as in tenant discovery appliance url>
## Please use only alphanumeric value in COMPANY_NAME
COMPANY_NAME=
TENANT_EMAIL=
TENANT_FIRST_NAME=
TENANT_LAST_NAME=
TENANT_TYPE=
# Ensure that the value of COUNTRY is enclosed within double quotes
COUNTRY="Virgin Islands, U.S."

#SMTP Config
#SMTP_HOST=<SMTP host name of IP address accessible from cluster>
#SMTP_PORT=<SMTP server port, e.g. 25>
#SMTP_USERNAME=<SMTP user name>
#SMTP_FROM_EMAIL=<SMTP from email address>
#SMTP_TLS=<true/false>
#This below variable is used by portal team
#SMTP_AUTH=<PLAIN or LOGIN or NONE>
# If you use NONE it will not skip the validation of SMTP but it means that your organization allows you to send email without SMTP authentication.
# PLAIN or LOGIN is used when you have authenticated SMTP user and SMTP password
#This variable is used for getting report email to dahsboard team by default value is true
#SMTP_AUTH_DASHBOARD=<true or false>
#OPS_GROUP_EMAIL=<ops email address>
#APPROVAL_GROUP_EMAIL=<email address for approval>
SMTP_HOST=
SMTP_PORT=
#Ensure blank values for SMTP username password is in double quotes
SMTP_USERNAME=
SMTP_FROM_EMAIL=
## SMTP_TLS value can be true or false.
## If SMTP_TLS is set to true and certificate of SMTP_HOST is signed by a custom or self-signed CA then
## ensure to append custom or self-signed CA certificate (full CA chain) to commons/certs/custom_cacert.pem file.
SMTP_TLS=false
SMTP_AUTH_DASHBOARD=true
SMTP_AUTH=
OPS_GROUP_EMAIL=
APPROVAL_GROUP_EMAIL=

#storage class, set value as per storage class in cluster
#PG_STORAGE_CLASS=onprem-storage
#VMSTORAGE_STORAGE_CLASS=onprem-storage
#VMAGGSTORAGE_STORAGE_CLASS=onprem-storage
#ES_MASTER_STORAGE_CLASS=onprem-storage
#ES_DATA_STORAGE_CLASS=onprem-storage
#MINIO_STORAGE_CLASS=onprem-storage
#EFS_STORAGE_CLASS=onprem-storage
#REDIS_HA_GLOBAL_STORAGECLASS=onprem-storage
#KAFKA_STORAGECLASS=onprem-storage
#ESLOG_MASTER_STORAGE_CLASS=onprem-storage
#ESLOG_DATA_STORAGE_CLASS=onprem-storage
#AIOPS_STORAGE_CLASS=onprem-storage

PG_STORAGE_CLASS=
VMSTORAGE_STORAGE_CLASS=
VMAGGSTORAGE_STORAGE_CLASS=
ES_MASTER_STORAGE_CLASS=
ES_DATA_STORAGE_CLASS=
MINIO_STORAGE_CLASS=
EFS_STORAGE_CLASS=
REDIS_HA_GLOBAL_STORAGECLASS=
KAFKA_STORAGECLASS=
ESLOG_MASTER_STORAGE_CLASS=
ESLOG_DATA_STORAGE_CLASS=
AIOPS_STORAGE_CLASS=

#Optimize storage details
#OPT_STORAGE_CLASS=onprem-storage
OPT_STORAGE_CLASS=

#CUSTOM_CA_SIGNED_CERT_IN_USE=true/false
#if you are using self-signed/custom CA signed certificate please set it to true,
#also ensure you have copied custom CA certificate file at commons/certs directory with file name custom_cacert.pem i.e. commons/certs/custom_cacert.pem
CUSTOM_CA_SIGNED_CERT_IN_USE=false

# If there are no permissions to create ServiceAccount, Role, RoleBinding then, create a serviceaccount and assign it to CUSTOM_SERVICEACCOUNT_NAME by replacing default value of helix_onprem_sa.
# Ensure to create a role and rolebinding from file commons/yaml_files/role_rolebinding.yaml and a serviceAccount from file commons/yaml_files/serviceAccount.yaml.
# If there are permissions to create ServiceAccount, Role, RoleBinding then do not change CUSTOM_SERVICEACCOUNT_NAME from value helix-onprem-sa.
CUSTOM_SERVICEACCOUNT_NAME=helix-onprem-sa

# If you want to use custom JAVA keystore for "RSSO SAML keystore configuration", then you must set variable RSSO_CUSTOM_JAVA_KEYSTORE_IN_USE to true
# and put the custom java keystore file at commons/certs directory with file name rsso_custom_java_keystore
# i.e. commons/certs/rsso_custom_java_keystore
# The file commons/certs/rsso_custom_java_keystore will be mounted inside RSSO container at location /etc/rsso_custom_java_keystore
# SAML Keystore - this is the Keystore used for reading SAML-specific certificates/keys. So, it's an application-level Keystore, used directly by the app.
# While JVM Keystore contains certificates for HTTPS connections, the SAML Keystore is used for storing signing and encryption certificates for communication with SAML v2 IdP.
RSSO_CUSTOM_JAVA_KEYSTORE_IN_USE=false  

# Smart Graph
#SMART_SYSTEM_USERNAME=system
SMART_SYSTEM_USERNAME=""

# Ingress class used while deploying Ingress controller
INGRESS_CLASS=nginx

#Binary paths on your system
#HELM_BIN=/usr/local/bin/helm
#KUBECTL_BIN=/usr/bin/kubectl
HELM_BIN=
KUBECTL_BIN=
#OC_BIN path should be set if CLUSTER_TYPE is openshift or ocp
#OC_BIN=/usr/local/sbin/oc
OC_BIN=

# Infra components will run with below Security Context.
# Below 3 variables are considered only for OpenShift cluster
# i.e. if CLUSTER_TYPE is openshift or ocp
# Set correct context as per the OpenShift namespace.
# Else RUN_AS_USER, RUN_AS_GROUP and FS_GROUP must be null.
RUN_AS_USER=null
RUN_AS_GROUP=null
FS_GROUP=null

# Optimize Security Context:
# OPT_FSGROUP must have value 87654321 if CLUSTER_TYPE is openshift or ocp and INSTALL_MODE is upgrade and fresh deployment was performed with 22.2.01 version
# Else OPT_FSGROUP must have value 1001
OPT_FSGROUP=1001

# If CLUSTER_TYPE is openshift or ocp  and INSTALL_MODE is fresh then ML_FSGROUP must be same as FS_GROUP mentioned above, else ML_FSGROUP must have value 998
ML_FSGROUP=998

################################### DO NOT CHANGE ANYTHING BELOW THIS LINE ##########################################

#Patroni Postgres config
PG_HOSTNAME=postgres-bmc-pg-ha-pool
PG_USER=postgres
PG_DATABASE=postgres


#Redis HA config
REDIS_HA_HOSTNAME=redis-redis-ha-haproxy

#Kafka & Zookeeper config
KAFKA_HOSTNAME=kafka
ZOOKEEPER_HOSTNAME=kafka-zookeeper

#RSSO Config
RSSO_PG_DB=ade_rsso

#Elasticsearch config
ES_EVENTS_HOSTNAME=elasticsearch-events-opendistro-es-data-svc
ES_LOGS_HOSTNAME=elasticsearch-logs-opendistro-es-data-svc

#MinIO config
MINIO_HOSTNAME=minio

# Misc
IMAGE_REGISTRY_SECRET=bmc-dtrhub
TENANT_PHONE=1234567890
LOGIN_ID=hannah_admin

Sample deployment.config file
#Common config begin
#Size of deployment, values are compact, small, medium, large, itsmcompact, and itsmsmall
DEPLOYMENT_SIZE=small

#Docker registry project details
IMAGE_REGISTRY_PROJECT=bmc
IMAGE_REGISTRY_ORG=lp0lz
CORE_IMAGE_REGISTRY_ORG=lp0lz
IA_IMAGE_REGISTRY_ORG=lp0oz
OPTIMIZE_IMAGE_REGISTRY_ORG=lp0pz
BHOM_IMAGE_REGISTRY_ORG=lp0mz
AIOPS_IMAGE_REGISTRY_ORG=la0cz

#Common config end

#Install mode as fresh or upgrade
INSTALL_MODE=fresh

#Flag controlling infra services installation
INFRA=yes

#Flag controlling individual infra services installation
_PTPOSTGRESS=yes
_KAFKA=yes
_REDIS=yes
_RSSO=yes
_VICTORIAMETRICS=yes
_ELASTICSEARCH=yes
_MINIO=yes

# Do not make changes to service flags it will break dependency
#Flag controlling helix dashboard services installation
HELIX_DASHBOARD_SERVICES=yes

#Flag controlling itsminsight services installation
ITSMINSIGHT_SERVICES=no

#Flag controlling aiops services installation
AIOPS_SERVICES=no

#Flag controlling monitor product installation
MONITOR=no

#Flag controlling intelligentintegrations services installation
INTELLI_INT_SERVICES=no

#Flag controlling intelligent automation product installation
INTELLIGENT_AUTOMATION=no

#Flag controlling bmc-helix-logging product installation
BMC_HELIX_LOGGING=yes

#Flag Controlling optimize installation
OPTIMIZE=no

#Flag AR Services installation
ARSERVICES=yes

Where to go from here

Next task

Back to process

If you are finished setting up the installation environment, return to the appropriate installation, update, or upgrade process:




 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*