Skip to Content

Changing the domain name

 

You can change the BMC Helix Service Management domain name to align with a new organizational domain, certificate, or DNS configuration. This operation ensures that all the platform components and Service Management applications use the updated domain name for authentication, service mapping, and access.

Information
Scenario

Apex Global is transitioning from the old domain oldcompany.com to the new domain newcompany.com. This change affects user accounts, email addresses, authentication systems, and integrated applications across the organization.  To implement this change, the system administrator updates the domain configuration in the on-premises environment to ensure all systems reflect the new domain name.

Before you begin

Make sure that you meet the following requirements:

  • The BMC Helix Platform Common Services and BMC Helix Service Management deployment is complete, and all pods are in the running state.

  • The DNS and load balancer entries for the new domain host names are configured for the following components:

    • BMC Helix Platform Common Services
    • BMC Helix Service Management services
  • The tctl utility is configured on the BMC Helix Platform Common Services namespace.
    For information about configuring the tctl utility, see Downloading and configuring the tctl utility
  • All configuration files, manifests, and database backups are available.
  • BMC Helix Service Management is licensed.

Task 1: To change the domain name in the BMC Helix Platform Common Services namespace

  1. To edit the Tenant Management Service (TMS) deployment in the Kubernetes cluster where BMC Helix Platform Common Services is deployed, run the following command:kubectl edit deployment tms -n <BMC Helix Platform Common Services namespace>

  2. In the env section, add the following environment variables:
    env:
      - name: ADE_TENANT_IGNORE_DOMAIN_VALIDATION
        value: "TRUE"

  3. To set a new domain alias, perform the following steps:
    1. Log in to the tctl utility.
    2. Create a JSON file that contains the new domain name by using the following format:{

       "domain": "<Environment>.<new domain>",

       "serviceUrlMappings": {}

      }
    3. Run the following command:
      tctl set domain <tenant_id> -f <JSON file name>
      This command performs the following actions:
      • Adds the new alias domain in TMS.
      • Updates the BMC Helix Single Sign-On (SSO) tenant host, cookie domain, and OpenID Connect issuer URL.
      • Adds redirect URLs for service mappings.
      • Updates service URLs in Identity Management Service (IMS) for relevant services.

  4. Disable the API key authentication validation by using the following command:
    kubectl -n <BMC Helix Platform Common Services namespace> set env deployment data-download-gateway-service event-service open-data-gateway-service metric-gateway-service API_KEY_AUTH_VALIDATION=false

  5. (Optional) If you are using a self-signed certificate in your environment, update the following namespaces with the new self-signed certificate:

    1. In the Ingress controller namespace, update the Kubernetes secret my-tls-secret with the new certificate.

    2. In the BMC Helix Platform Common Services, add the new certificate.
      For information about adding the certificate, see Updating expired certificates in the BMC Helix IT Operations Management deployment documentation.

Task 2: To verify the BMC Helix Platform Common Services domain name change

Perform this task to verify that the tenant details reflect the updated domain in the BMC Helix Platform Common Services namespace.

  1. To get the tenant details, run the following command:
    tctl get tenant <tenant_id> -o json

    Example output command:{

      "id": "1659548410",

      "domain": "smartoneitsm-private-prd.<domain>",

      "alias_domains": [

        { "domain": "smartoneitsm-private-prd.<old domain>", "status": "ACTIVE" },

        { "domain": "smartoneitsm-private-prd.<domain>", "status": "ACTIVE" }

      ]

    }

     

  2. Update the awss3secret secret file with the new MinIO URL values in an encrypted form for the following keys:
    kubectl edit secret awss3secret -n <BMC Helix Platform Common Services namespace> 

    • AWS_S3_ENDPOINT
    • AWS_S3_ENDPOINT_HS
    • AWS_S3_ENDPOINT_WITH_REGION

Task 3: To update the single-sign-on and database configurations

Perform this task to verify that the tenant details reflect the updated domain in BMC Helix Single Sign-On URL and IMS and TMS databases.

  1. To update the OpenID Connect issuer URL and cookie domain, perform the following steps:
    1. Log in to the BMC Helix SSO Admin Console.
    2. On the OAuth2 tab, update the OpenID Connect issuer URL to reflect the new BMC Helix SSO URL.
    3. On the General tab, update the cookie domain to the new domain value.
  2. To update BMC Helix SSO Ingress host names, perform the following steps:
    1. Back up all ingress configurations by using the following command:

      kubectl -n <namespace> get ing -o yaml > all_ingress.yaml
       
    2. Edit all ingresses together, by using the following command:

      kubectl -n <namespace> edit ing
       
    3. In the edit mode, press escape and type the following command, including colon (:) to replace old domain references with the new domain:

      :%s/<old-domain>/<new-domain>/g 

      Example:

      :%s/abc.com/xyz.com/g

      This command replaces all instances of the old domain with the new domain.
       
    4. Save and exit the file.
       
  3.  To update BMC Helix SSO URLs in IMS and TMS databases, perform the following steps:
    1. Access the PostgreSQL pod in the BMC Helix Platform Common Services namespace by using the appropriate exec command.
      The command might vary depending on the PostgreSQL pod version in your environment:$ kubectl exec -it postgres-bmc-pg-ha-15-0 -c postgres-bmc-pg-ha-15 -n <namespace> -- bash
    2. Connect to the PostgreSQL database by using the following command:[postgres@postgres-bmc-pg-ha-15-0 /]$ psql -U postgres -h postgres-bmc-pg-ha-15-pool -d postgres

      •  

    3. Update the tenant record by using the following command:

      UPDATE master.tenants SET rsso_url = 'https://new-rsso-ingress-hostname/rsso' WHERE tenant_id = '<TENANT_ID>'; 

      Example command:

      UPDATE master.tenants SET rsso_url = 'https://smartoneitsm-prd-lb.<domain>/rsso' WHERE tenant_id = '1324797545';
    4. Connect to the TMS database, update the BMC Helix SSO configuration JSON entry, and run the following query to save the updated configuration:

      SELECT rsso from master.environment WHERE id = '<TENANT_ID>'

      Example command:SELECT rsso from master.environment WHERE id = '1324797545';
    5. Replace the old URL in the BMC Helix Single Sign-On JSON file with the new URL and run the following query:

      UPDATE master.environment SET rsso='{"url":"https://smartoneitsm-stg-lb.<domain>/rsso","realmid":"smartoneitsm.476320676"}' WHERE id='476320676';
      UPDATE master.environment SET rsso='{"url":"https://smartoneitsm-prd-lb.<domain>/rsso","realmid":"smartoneitsm.1324797545"}' WHERE id='1324797545';
    6. In the BMC Helix Platform Common Services namespace, in the rsso-admin-tas ConfigMap, update the URL.
  4. To update the rsso-admin-tas ConfigMap, perform the following steps:
    1. Edit the ConfigMap by using the following command: 
      kubectl edit cm rsso-admin-tas -n <namespace>
       
    2. Update the URL to the new BMC Helix SSO URL.
    3. Save and exit.
    4. Restart all pods by running the following command:
      kubectl get pod -n bmchlx-platform | grep -iv "postgres\|redis\|kafka-exporter\|kafka-0\|kafka-1\|kafka-2\|kafka-zookeeper\|victoria\|rsso-" | grep Running | awk '{print $1}' | xargs kubectl delete pod -n bmchlx-platform
       
    5.  Restart the Redis pods by running the following command:
      kubectl get pod -n bmchlx-platform | grep -iv "redis-redis-ha-" | grep Running | awk '{print $1}' | xargs kubectl delete pod -n bmchlx-platform
       

Task 4: To change the domain name in the BMC Helix Service Management namespace

  1. Log in to your Jenkins server by using the following URL:
    http://<Jenkins server host name>:8080
  2. Select the HELIX_ONPREM_DEPLOYMENT pipeline, select the latest successful build, and then click Rebuild.
  3. In the ENVIRONMENT DETAILS section, specify the following parameter values:
    ParameterDescription
    DEPLOYMENT_MODESpecify the parameter value as SERVICE

    CUSTOMER_SERVICE and ENVIRONMENT

    Specify the values of your service and environment.
    The pipeline generates URLs in a specific format based on the inputs provided in the CUSTOMER_SERVICE, ENVIRONMENT, and APPLICATION_PARENT_DOMAIN parameters.

    Example: If CUSTOMER_SERVICE=itsm, ENVIRONMENT=poc, and CLUSTER_DOMAIN=aus-ranch.bmc.com, the following URLs are be generated for different applications:

    Mid Tier—itsm-poc.aus-ranch.bmc.com Smart IT—itsm-poc-smartit.aus-ranch.bmc.com Innovation Studio—itsm-poc-is.aus-ranch.bmc.com Innovation Suite REST API or CMDB—itsm-poc-restapi.aus-ranch.bmc.com Atrium Web Services—itsm-poc-atws.aus-ranch.bmc.com Digital Workplace—itsm-poc-dwp.aus-ranch.bmc.com Digital Workplace Catalog—itsm-poc-dwpcatalog.aus-ranch.bmc.com Live Chat—itsm-poc-vchat.aus-ranch.bmc.com Openfire Chat—itsm-poc-chat.aus-ranch.bmc.com Support Assistant tool—itsm-poc-supportassisttool.aus-ranch.bmc.comThe platform and application URLs support only the HTTPS protocol.

    Important: 

    When the ENVIRONMENT value is prod for production environments, the URLs are generated by excluding -<ENVIRONMENT> value.
    Example, the URL format for Mid Tier production environment is itsm.aus-ranch.bmc.com
    The URL format for Smart IT production environment is itsm-smartit.aus-ranch.bmc.com.

    APPLICATION_PARENT_DOMAINSpecify the Ingress controller domain name that is used for application URLs.
    CUSTOM_CERTIFICATE

    If you want to use a custom CA certificate or self-signed certificate for the new domain, click Browse and upload your custom cacerts file.

  4. In the PIPELINES section, select the checkboxes for the following parameters:

    • HELIX_GENERATE_CONFIG
    • HELIX_PLATFORM_DEPLOY
    • HELIX_NONPLATFORM_DEPLOY
    • HELIX_SMARTAPPS_DEPLOY
    • SUPPORT_ASSISTANT_TOOL
    • HELIX_INTEROPS_DEPLOY

  5. In the RSSO PARAMETERS section, in the RSSO_URL parameter, specify the BMC Helix Single Sign-On URL that you used for deploying BMC Helix Platform Common Services.

    Example: specify https://<LB_HOST>/rsso 

    LB_HOST is the load balancer host name that you used in the infra.config file during the BMC Helix Platform services deployment.

    Information
    Important

    Make sure that you do not specify a forward slash ( / ) at the end of the URL.

    1. In the ITSM INTEROPS PARAMETERS section, in the HELIX_PLATFORM_DOMAIN parameter, specify the domain name of the cluster where BMC Helix Platform Common Services is installed.
    2. Click Rebuild.

Task 5: To verify the BMC Helix Service Management domain name change

  1. Verify that you can log in to the Service Management applications.
  2. Verify that you can access the application URLs from BMC Helix Portal.
    If you are unable to access the application URLs from BMC Helix Portal, and the URLs are redirected to an old domain, perform the following steps:
    1. Deactivate the tenant services, and then activate the tenant services.
    2. Verify the pod logs for any old domain reference.
    3. If a pod has the old domain reference, restart the pod.
    4. Log in to BMC Helix Portal and verify that the application URL is accessible.
  3. Remove the old iFrame references by performing the following steps:
    1. Log in to Innovation Studio.
    2. In the Administration tab, in the Settings pane, click Integrations.
    3. In the Data Sources option, click Iframe security.
    4. In the Iframe security pane, in the Trusted Web Applications field, add the application URLs.

Troubleshooting BMC Helix Digital Workplace URL redirection issue

After performing the BMC Helix Service Management domain name change, the BMC Helix Digital Workplace pod does not reference the new domain or redirect to the updated URL.

Issue symptoms

  • BMC Helix Digital Workplace pod refers to the old domain.
  • URL redirection to the new domain does not occur.

Issue scope

  • Affects BMC Helix Digital Workplace pod configured with outdated domain references.
  • Impacts components relying on the following parameters:
    • vaChatUrl
    • myitBackendUrl
    • iframeAllowedSites

Resolution

  1. To verify the BMC Helix Digital Workplace pod logs, perform the following steps:

    • Review the pod logs to confirm if the pod is referencing the old domain.
    • Identify warnings or errors related to URL redirection or configuration loading.

  2. To update the configuration settings in BMC Helix Innovation Studio, perform the following steps:

    1. Log in to  BMC Helix Innovation Studio.
    2. Navigate to the dwp:ConfigurationParams record definition.
    3. Locate entries for the following parameters:
      • vaChatUrl
      • myitBackendUrl
      • iframeAllowedSites
    4. Update each parameter value to reflect the new domain.

  3. Restart the pod.

  4. Verify that the pod references the new domain and URL redirection works.

Troubleshooting Helm version mismatch

When running the BMC Helix Service Management deployment pipeline, the process fails due to a Helm version mismatch. This issue occurs when the Helm chart version in the installer repository differs from the expected target version.

Issue symptoms

  • The deployment pipeline fails with a message indicating a Helm version mismatch.
  • The logs show mismatched values in the HELM_VERSION, TARGET_VERSION, or SMARTAPPS_HELM_VERSION parameters.

Issue scope

This issue occurs during the HELIX_ONPREM_DEPLOYMENT pipeline execution, after updating the repository templates, or during upgrades.

Resolution

Perform the following steps to troubleshoot Helm version mismatch:

  1. Log in as the Git user by running the following commands:su git
    cd /home/git/git_repo/ITSM_REPO

     

  2. To clone the repository, run the following commands:
    git clone itsm-on-premise-installer.git
    cd itsm-on-premise-installer/pipeline/tasks/inputTemplates/
  3. Edit the file itsmtemplate_xlarge.sh and manually update the following parameter values:
    • HELM_VERSION="2023304.1.00.00"
    • TARGET_VERSION="2023304.1.00.00"
    • SMARTAPPS_HELM_VERSION="2023304.1.01.00"
  4. To commit and push the changes, run the following command:
    git add -A
    git commit -am "helm version corrected"
    git push origin master

Where to go from here

Administering

 

 

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

BMC Helix Service Management Deployment 25.3.01