Changing the domain URL post-deployment

As an administrator, you can change the domain URL of BMC Helix IT Operations Management after deployment. Changing the domain is typically required when the deployed environment must align with a new organizational domain, certificate, or DNS configuration. This operation ensures that all components, such as BMC Helix Platform, BMC Helix Discovery, BMC Helix Optimize, and BMC Helix Service Management, use the updated domain name for authentication, service mapping, and access.

Before you begin

Task 1: To allow domain validation bypass

1. To edit the Tenant Management Service (TMS) deployment, run the following command on the Kubernetes cluster where BMC Helix Platform is deployed:

2.  In the env section, add the following environment variable:

Task 2: To set the new alias domain by using the tctl utility

1. Prepare a JSON file that contains the new domain name and service URL mappings.
   Example:

2.  Before using tctl config, update the following configuration parameters with the new domain:

Parameter	Value
apiexitreturn	"true"
appurl	<tms url with new domain>
clientid	<id>
clientsecret	< >
enableauth	"true"
forceprompt	"true"
rssourl	<rsso url with new domain>

For more information, refer to Using the tctl utility.

3. Run the following command to set the new domain alias:
   
   tctl set domain <tenant_id> -f <json_file>
    

In the above command replace <tenant_id> with your tenant ID and <json_file> with the file name created in the previous step. 

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.

(Optional) Task 3: To disable authentication validation

Perform this task if you have deployed BMC Helix Operations Management or BMC Discovery in your environment.

The value of the JWT_AUTH_VALIDATION parameter is now set to false for all service deployments.

(Optional) Task 4: To update BMC Discovery database details for the short URL

Perform this task if you have deployed BMC Helix Operations Management or BMC Discovery in your environment.

1. Log in to the Kubernetes master node or any node with kubectl access to the bmchlx-platform namespace.
2. From the deployment utilities, copy the smartgraph_db_update.yaml file to a temporary working folder on the node.

3. Edit the file and update the following values to match your environment:

   Field name	Action
   namespace	Enter the namespace value.
   UUID	Enter the tenant UUID.
   tenant_portal	Enter the tenant portal URL.
   discovery_portal	Enter the discovery portal URL.

4. Run the following command to apply the changes:

(Optional) Task 5: To update the self-signed certificate

Perform this task if you have deployed BMC Helix Operations Management or BMC Discovery in your environment.

If the BMC Helix IT Operations Management deployment uses self-signed certificates, you must update the certificates whenever the domain name changes. This requirement is required because self-signed certificates are tied to a specific domain, and any change in the domain invalidates the existing certificate.

Perform the following steps to replace the old certificate with a new one that matches the updated domain:

1. Update the Kubernetes secret my-tls-secret with the new self-signed certificate in the Ingress controller namespace.
2. Update the certificate in the IT Operations Management namespace to ensure all components trust the new domain.
   For more information, see the "Updating the CA certs" topic in Updating expired certificates.

Task 6: To verify the dashboard and SSO configuration

1. Access the BMC Helix IT Operations Management dashboard manually by using the new domain.
2. Select Administration > BMC Helix SSO.

3. Update the following values:

   Field name	Action
   HSSO Server URL	Update with the new SSO URL.
   OpenID Connect Client ID	Verify the correct value from the smart-graph-oauth secret in the IT Operations Management namespace, and update it if required.
   OpenID Connect Client Secret	Ensure that the field is blank (do not select the checkbox).
   Optional Helix Platform IMS URL	Update with the latest domain.

4. To confirm that the certificate is issued for the new domain, perform the following steps:
   1. Select BMC Discovery > Single Sign-On in the dashboard.
   2. Locate the Certificate section.
   3. Verify that the displayed certificate corresponds to the new domain.

Task 7: To verify the domain change in the Helix Platform namespace

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

1. Run the following command inside the tctl utility to get the tenant details:

2. Verify that the command output includes both the old and new domain entries under alias_domains.
   Example:

3. Update the secret awss3secret file with the correct URLs:

   • AWS_S3_ENDPOINT
   • AWS_S3_ENDPOINT_HS
   • AWS_S3_ENDPOINT_WITH_REGION

Task 8: To update BMC Helix SSO configuration and database entries

1. Update the OpenID Connect issuer URL and cookie domain:
   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. Update BMC Helix SSO ingress hostnames:
   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 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.
      For example, the above steps will change all occurrences of example.com to bmc.com.
       
3.  Update BMC Helix SSO URLs in imsdb and tmsdb:
   1. Access the Postgres pod in the BMC Helix Platform namespace by using the appropriate exec command, which might vary depending on the Postgres 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 Postgres database by entering the following command:[postgres@postgres-bmc-pg-ha-15-0 /]$ psql -U postgres -h postgres-bmc-pg-ha-15-pool -d postgres

      •  

   3. Run the following query in imsdb to update the tenant record:
      
      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 tmsdb 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 rsso_url in rsso json with the new url and run 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. Update rssourl in rsso-admin-tas configmap in Helix platform namespace.
4. Update the rsso-admin-tas ConfigMap:
   1. Edit the ConfigMap by entering the following command:

      • kubectl edit cm rsso-admin-tas -n <namespace>

   2. Update the rssourl value 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 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-platfor

Task 9: To run the CCS job by using tctl

1. Create a JSON file ccs.json with the following content:

   • {

       "jobs": [

             {

              "label":"ITSM_CCS_PARAMS"

         }

         ]

     }

2.  Run the following command:

   • tctl update tenant <tenant_id> -f ccs.json

3.  Verify the output similar to the following:

   • {
       "jobs": [
         {
           "label": "ITSM_CCS_PARAMS",
           "tenant_id": 1324797545,
           "status": "RUNNING",
           "run_date_time": "2025-05-23T11:54:49.124927"
         }
       ]
     }

Troubleshooting Helm version mismatch

When running the deployment pipeline for BMC Helix Operations Management, the process might fail due to a Helm version mismatch. This typically happens when the Helm chart version in the installer repository differs from the expected target version defined in the deployment templates.

Issue symptoms

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

Issue scope

• Occurs during pipeline execution for on-premise installations.
• Might occur after updating repository templates or during version upgrades.
• The issue occurs when deploying or upgrading BMC Helix ITSM components using the itsm-on-premise-installer repository.

Resolution

Perform the following steps to troubleshoot Helm version mismatch:

Where to go from here

Deploying BMC Helix IT Operations Management in a multitenant environment