Required Helm Chart configuration for HCL Commerce Version 9.1

Common configuration values

The following values are required to be modified in your my-values.yaml file to match the environment and cluster configuration that you want:


Parameter	Description
license	You must accept the license before you can deploy HCL Commerce. To view the license, browse all of the files under the LICENSES directory. To accept the license, set  license  to  `accept`.
common.tenant common.environmentName common.environmentType	The common.tenant value can be your organization name. You can have multiple environments under the same tenant. The common.environmentName is the name of the environment. Some examples of environment name are `dev`, `qa` or `production`. Each HCL Commerce environment can be used to partition logical groups of different hosted applications. The common.environmentType is the specific environment type. For each environment, an environment type must be specified: `auth` holds the HCL Commerce staging applications used by administration and business users. `live` holds the production applications to serve live traffic to end users of your storefront. `share` holds the applications that can be consumed by both `auth` and `live` environment types. For example, the new Search solution and new tooling are deployed in the `share` group.  In addition to organizing your site, the tenant, environment name, and environment type values are used together to form the path to look up environment configuration values in Vault. Important: These values should contain lower case characters only, without spaces or special characters.
common.vaultTokenSecret	The name of the secret object which contains the Vault token. Refer to Deploying a development Vault for HCL Commerce on Kubernetes and Prerequisites for deploying HCL Commerce on a Kubernetes cluster to understand how the Vault token is passed to HCL Commerce.
common.dbType	The type of database that the environment is using. Valid values are `db2` and `oracle`.
common.imageRepo	The Docker Registry repository in `docker_registry_domain`:`port` format.
common.spiUserName	The SPI user name used for basic authentication with server to server communication. `spiuser` is the default value used for HCL Commerce.
common.spiUserPwdAes	The spiuser user password, encrypted with AES by the wc_encrypt utility. The default plain text password is : For HCL Commerce 9.1.0.0 to 9.1.8.0, the password is `passw0rd`, which when encrypted corresponds with the default key, `eNdqdvMAUGRUbiuqadvrQfMELjNScudSp5CBWQ8L6aw`. For HCL Commerce 9.1.9.0 or greater, the password is `QxV7uCk6RRiwvPVaa4wdD78jaHi2za8ssjneNMdu3vgqi`, which when encrypted corresponds with the default key, `cSG7n0iFVpt+Az2JUKeJQJGOXfDkZUUpIYCS1hJXL9hYK3yaSQ2ssVCoz/SKoaCH3g+g+9FGcLejkI/KpJLI5Q==`. You can use the default key to match the sample db2 database Docker container. For more information, see Setting the spiuser password in your Docker images.
common.spiUserPwdBase64	The Base64 encoded value for  `spiuser`:`password`. The default plain text password is: For HCL Commerce 9.1.0.0 to 9.1.8.0, the password is `passw0rd`, or  `c3BpdXNlcjpwYXNzdzByZA==`  in Base64. For HCL Commerce 9.1.9.0 or greater, the password is `QxV7uCk6RRiwvPVaa4wdD78jaHi2za8ssjneNMdu3vgqi`, or  `c3BpdXNlcjpReFY3dUNrNlJSaXd2UFZhYTR3ZEQ3OGphSGkyemE4c3NqbmVOTWR1M3ZncWk=`  in Base64. This value can be obtained by piping the values through the Base64 system utility: `echo -n spiuser:password \| base64`
common.vaultUrl	The Vault V1 API URL. The default value is `http://vault-consul.vault.svc.cluster.local:8200/v1` Note: This value assumes that hcl-commerce-vaultconsul-helmchart was used to deploy Vault into the `vault` namespace.
common.externalDomain	The external domain used for ingress and the Store Preview URL. In the hostname `store.demoqaauth.mycompany.com`, `.mycompany.com` would be the external domain name.
common.configureMode	HCL Commerce supports `Vault` and `EnvVariables` configuration modes. The default value is `Vault`, which is also the recommended configuration mode.
common.imagePullSecrets	The name of the secret name which contains the credential for pulling images from your Docker Registry. Leave this value empty if the Docker Registry that is used does not require authentication.
common.imagePullPolicy	The policy to control when to pull Docker images. Valid values are `IfNotPresent` and `Always`.
common.serviceAccountName	The service account name which binds to the necessary roles to deploy HCL Commerce. By default, this value is `default`.
common.dataIngressEnabled	Deprecated: This parameter was deprecated and removed in version 9.1.7.0. When this parameter is set to `true`, it will create ingress to the Elasticsearch services such as Nifi, Ingest, and Data Query services. This must be set to `false` for production environments to avoid security impact.
common.localStoreEnabled	When migrating from IBM Websphere Commerce Version 7 or IBM Websphere Commerce Version 8, there is an option to a deploy and host a store based on the Aurora-based solution from within the Transaction server. In this case, set localStoreEnabled to `true` to allow Elasticsearch and Ingress to be configured properly. This is not enabled by default, as the Aurora-based store solution that is included with HCL Commerce Version 9 is remote by default.
logging.jsonLogging.enabled	The parameter to enable JSON logging. When this parameter is set to `true`, it will enable JSON logging for all application servers. Accepted values are `true`, to enable logging, and `false` to disable JSON logging.
common.ipv6Enabled	The parameter to enable IPV6. When disabled, HCL Commerce applications will add the `java.net.preferIPv4Stack=true` JVM parameter, and use IPv4. Accepted values are `true`, to enable IPv6, and `false`  to use IPv4.
common.timezone	The timezone in ICANN TZ format. For example, `America/Toronto`. This parameter can also be set in all HCL Commerce containers as an environment variable, TZ. If this value is not set, or empty, `GMT` will be used in all containers by default. Warning: Changing the time zone will have impacts on HCL Commerce business logic, such as marketing web activities and promotion start and end dates and times. The values that are set for these site behaviors will not automatically adjust based on this timezone setting. It is recommended to keep this value empty if your site is already being used in a live production environment.
vaultCA.enabled	The parameter to enable Vault as a Certificate Authority to issue certificates. The default value is `true`.
ingressSecret.autoCreate ingressSecret.replaceExist	IngressSecret is used to specify whether to auto-generate and replace the secret for ingress. The default for both parameters is `true`.

HCL Cache and Metrics and Service monitor configuration values


Parameter	Description
metrics.enabled	The parameter to enable metrics for HCL Commerce. The default for this parameter is `true`.
metrics.serviceMonitor.enabled	The parameter to enable service monitoring with Prometheus. The default for this parameter is `false`.

Search index job configuration

When the Elasticsearch-based search solution is in use, an optional search index job can be triggered at deployment time. When the job is created, it monitors and waits for the required components, such as search-nifi and search-ingest, to be ready, and then triggers the build index for your specified stores. The job also monitors the build status and waits for it to complete.

Note: This option is for the Elasticsearch-based solution only. It is not compatible with the Solr-based solution.


Parameter	Description
searchIndexCreation	The parameter to enable an Elasticsearch-based search solution index build on deployment. Accepted values are `true` to enable the index build job, or `false` to disable the index build job.
searchIndexCreation.pushToLiveEnabled	The parameter to enable the push-to-live index connector portion within the index build job. Accepted values are `true` to enable the push-to-live index connector, or `false` to disable the push-to-live index connector.
searchIndexCreation.overalMaxDuration	The maximum duration, in seconds, for the job to complete before it is canceled due to timeout. This value must take into account the number of stores that are indexed, the data set size, and the index build complexity of each store. If the value is not sufficiently set with a generous margin, then the job can be unintentionally canceled before it otherwise would have completed successfully.
searchIndexCreation.indexMaxDuration	The maximum duration, in seconds, for each individual index run to be canceled before timeout.
searchIndexCreation.interval	The interval, in seconds, for the index build job to wait in between each readiness check for each required search component.
searchIndexCreation.txnMaxDuration	The maximum time, in seconds, to wait for the Transaction server to be ready.
searchIndexCreation.nifiMaxDuration	The maximum time, in seconds, to wait for the NiFi application to be ready.
searchIndexCreation.ingestMaxDuration	The maximum time, in seconds, to wait for the ingest application to be ready.
searchIndexCreation.maxRetry	The maximum number of retries for each index build run, in the event that the index build job fails.
searchIndexCreation.storeIds	A list of store IDs, separated by commas, to run the index builds against.
searchIndexCreation.calculatePriceEnabled	The parameter to enable price calculation for B2B stores. Accepted values are `true` to enable price calculation, and `false` to disable price calculation.
searchIndexCreation.calculatePriceStoreIds	A list of store IDs, separated by commas, to run price calculation against.

Logging configuration

By default, the HCL Commerce applications do not provide logging in JSON format, but rather in the format that is specified in each server individually. When aggregating this data within a centralized logging system, such as EFK, it is required to enable the JSON logging format.


Parameter	Description
logging.jsonLogging.enabled	The parameter to enable JSON logging. When this parameter is set to `true`, it will enable JSON logging for all application servers. Accepted values are `true`, to enable logging, and `false` to disable JSON logging.

Ingress configuration

Ingress is used to allow external access to applications that are deployed within a Kubernetes cluster. The HCL Commerce Helm Chart defines ingress, to allow access to the most commonly used services in HCL Commerce, such as Management Center for HCL Commerce, and the storefront. For each of these services, you can configure the  domain,  ingressClass  and  tlsSecret  for both authoring and live environments. You can use the ingress settings defined by the HCL Commerce Helm Chart, or use them as reference and define your own customized ingress based on your requirements.


Parameter	Description
ingress.enabled	Enable ingress creation. Accepted values are `true`, to enable ingress, and `false`  to disable ingress.
ingress.ingressController	The ingress controller type. Accepted values are: `nginx` `gke` `ambassador` `emissary` Note: For Amazon Elastic Kubernetes Service (EKS), the only supported ingress controller is  `nginx`. Set this parameter to `gke` when deploying on Google Kubernetes Engine (GKE) using the http(s) load balancing server as the ingress controller. If this parameter is set to `ambassador`, then Ambassador mapping resources are created instead of ingress resources. Restriction: With Kubernets 1.22 or greater, Ambassador ingress is not supported. Instead, Emissary is required. The Emisssary ingress controller also requires a version of HCL Commerce 9.1.12.0 or greater.
ingress.emissaryIdsList	The Ambassador ID list for the Emissary listener that is listening on HTTP and HTTPS ports. Leave this value empty if you are only using the default Ambassador ID. If you are using different Ambassador IDs that are defined in the ingress configuration for different components, then you must add them here to create listeners for different Emissaries.
ingress.apiVersion	The API version to use for Ingress. Use `networking.k8s.io/v1beta1` for kubernetes between 1.16 and 1.19 (exclusive). Use `networking.k8s.io/v1` for kubernetes 1.19 and greater. Using this version will avoid the API deprecation warning messages the previous `v1beta1`. For more information, see  https://kubernetes.io/docs/reference/using-api/deprecation-guide/#ingress-v122.
ingress.enableToolingForReactStore	The parameter to specify whether ingress for the Marketplace Approval service is enabled or disabled.
OpenshiftDeployment.destinationCACertificate	In an OpenShift Container deployment, the routes resources will be created directly instead of ingress. Specify the CA certificate to allow the HAProxy proxy to trust the certificate of HCL Commerce servers. The CA certificate is the one that you specified in Vault deployment.
ingressSecret.autoCreate	The parameter specifies if the Helm per-install is used to generate an ingress certification secret. This is a convenient way to generate the self-signed certificate for a testing environment.
ingressSecret.replaceExist	The parameter to specify if the existing ingress certification secret needs to be replaced when deployed.
ingress.enableManageApprovalPage	The parameter to specify whether ingress is enabled for the Manage Approval page used for the Marketplace approval service. Accepted values are: `true` for enabled. `false` for disabled. This is disabled (`false`) by default.

Persistent volume for the Assets Tool

The Assets Tool was reintroduced in HCL Commerce 9.1.8.0. A persistent volume with ReadWriteMany access can be created to store the assets that are added and managed via this Management Center tool.

For more information on the Assets Tool, see Assets tool.

For more information on persistent volumes in Kubernetes, see Persistent Volumes in the Kubernetes documentation.


Parameter	Description
commercenfs.enabled	When enabled as `true`, this parameter deploys the Kubernetes external-storage projects NFS provisioner for use with the Assets tool. For more information, see nfs-server-provisioner.
assetsPVC.enabled	Create a PersistentVolumeClaim (PVC) for the Assets Tool. If set to `true`, a PVC with `ReadWriteMany` access mode is created. If set to `false`, no PVC is created.
assetsPVC.storageClass	The storage class name that is used by the PVC for the Assets Tool. This resource provider must support the `ReadWriteMany` access mode.
assetsPVC.storage	The storage size that is assigned to the persistent volume.
assetsPVC.accessMode	The access mode of the PVC. This is required to be `ReadWriteMany` for the Assets Tool PVC.
assetsPVC.existingClaim.auth	If there is already an existing PVC for the Assets Tool in the authoring environment, you can assign it with this parameter.
assetsPVC.existingClaim.live	If there is already an existing PVC for the Assets Tool in the live environment, you can assign it with this parameter.

Integration with HCL Digital Experience

Note: If you do not have HCL Digital Experience, this section can be ignored.

These configurations enable HCL Commerce to integrate with existing auth and live HCL Digital Experience (DX) environments that are deployed in the same cluster as HCL Commerce.

Important:

Nginx ingress must be used to deploy HCL Commerce. GKE ingress is not supported.
With this configuration, DX is made to be accessible with the same domain name as HCL Commerce.


Parameter	Description
dx.enabled	The parameter to enable or disable DX configurations. The default for this parameter is `false`. This configuration is ignored if both dx.namespace.auth and dx.namespace.live do not have values.
dx.namespace.auth	The DX `auth` environment namespace. This must be in the same cluster as Commerce.
dx.namespace.live	The DX `live` environment namespace. This must be in the same cluster as Commerce.
dx.serviceName.auth	The `auth` DX routing (load balancer) service name. Accepted values are `haproxy` or `ambassador` based on the DX version. You can obtain the service name with `kubectl get service`.
dx.serviceName.live	The `live` DX routing (load balancer) service name. Accepted values are `haproxy` or `ambassador` based on the DX version. You can obtain the service name with `kubectl get service`.

Integration with LDAP

Beginning with HCL Commerce 9.1.9.0, HCL Commerce can be integrated with a number of popular Lightweight Directory Access Protocol (LDAP) services, or with a custom LDAP implementation.

The values here describe if LDAP integration is enabled, for which environment, and then how LDAP configuration details are provided to the deployment for each environment. The actual configuration details are provided separately depending on the configuration mode selected.

For more information, see Integrating HCL Commerce Kubernetes deployments with LDAP.


Parameter	Description
ldap.auth.enabled	Specifies if LDAP is enabled for the authoring environment. Accepted values are: `true` for enabled. `false` for disabled. Note: By default, Vault is the default configuration method. There is no parameter required to specify this method of LDAP configuration.
ldap.auth.useVmmPropertiesFile	You can use the vmm.properties file to define LDAP configuration for a Kubernetes deployment by including a copy of it within a custom Transaction server Docker container. To use this configuration method, set this value to `true`, and then follow the instructions for Integrating HCL Commerce Kubernetes deployments with LDAP. Accepted values are: `true` for enabled. `false` for disabled.
ldap.auth.useConfigMapForVmmPropertiesFile	You can use the ldap-vmm-auth.properties configuration file to define LDAP configuration for a Kubernetes deployment. To use this configuration method, set this value to `true`, and then follow the instructions for Integrating HCL Commerce Kubernetes deployments with LDAP. Accepted values are: `true` for enabled. `false` for disabled.
ldap.live.enabled	Specifies if LDAP is enabled for the live environment. Accepted values are: `true` for enabled. `false` for disabled. Note: By default, Vault is the default configuration method. There is no parameter required to specify this method of LDAP configuration.
ldap.live.useVmmPropertiesFile	You can use the vmm.properties file to define LDAP configuration for a Kubernetes deployment by including a copy of it within a custom Transaction server Docker container. To use this configuration method, set this value to `true`, and then follow the instructions for Integrating HCL Commerce Kubernetes deployments with LDAP. Accepted values are: `true` for enabled. `false` for disabled.
ldap.live.useConfigMapForVmmPropertiesFile	You can use the ldap-vmm-auth.properties configuration file to define LDAP configuration for a Kubernetes deployment. To use this configuration method, set this value to `true`, and then follow the instructions for Integrating HCL Commerce Kubernetes deployments with LDAP. Accepted values are: `true` for enabled. `false` for disabled.

Deployment on Red Hat OpenShift

Deployment on Red Hat OpenShift is possible with the parameters specified in this section.

Red Hat OpenShift support was added in the following HCL Commerce releases:

Red Hat Plinux OpenShift
Red Hat Xlinux OpenShift

By default, OpenshiftDeployment.enabled is set to false.


Parameter	Description
OpenshiftDeployment.enabled	Enable deployment on Red Hat OpenShift. Accepted values are `true`, and `false`.
OpenshiftDeployment.SccName	The Security Context Constraints (SCC) that you want to be granted access for the deployment.
OpenshiftDeployment.destinationCACertificate	In an OpenShift Container deployment, the routes resources will be created directly instead of ingress. Specify the CA certificate to allow the HAProxy proxy to trust the certificate of HCL Commerce servers. The CA certificate is the one that you specified in Vault deployment.

Deployment with Google Anthos

Deployment with Google Anthos is possible with the parameters specified in this section. You can still use HCL Commerce with Google Anthos by manually updating the Helm Chart.

By default, AnthosDeployment.enabled is set to false.


Parameter	Description
AnthosDeployment.enabled	Introduced in HCL Commerce9.1.11.0, Google Anthos is supported by the HCL Commerce Helm Chart. Enable this feature for deployment when Google Anthos is used. This disables the istio sidecar injection for pre-install, pre-delete, create-index, nifi, and ingest to avoid failures. Note: You can still use older versions of HCL Commerce with Google Anthos by manually updating the HCL Commerce Helm Chart.

Deployment with Approvals in the Marketplace

Deployment with Approvals in the Marketplace is possible with the parameters specified in this section.


Parameter	Description
approvalApp.enabled	Introduced in HCL Commerce 9.1.12.0, the Approval service is used for approvals within a Marketplace. The Approval service application requires a separately deployed PostgresSQL that must be running before the service is started. The PostgreSQL database URL is passed to the Approval service using the Helm Chart where there is a `bootConfig` section under `approvalApp`.

Deployment with the Nextjs Ruby store

Deployment with Ruby is possible with the parameters specified in this section.


Parameter	Description
nextjsApp.enabled	Introduced in HCL Commerce 9.1.13.0, the Nextjs Ruby store is a starter store based on the Next.js framework that enables React-based web applications with server-side rendering and generation of static websites. For more information, see Next.js starter store.

Docker image configuration

Under each application definition (that is, definitions for tsApp, tsWeb, etc.), the image path is the path to the image relative to the common.imageRepo, and the tag defines the image tag. Ensure that each application has the correct image path and tag based on the actual images stored in your Docker Registry.

Kubernetes resource allocation

Under each application definition (that is, definitions for tsApp, tsWeb, etc.),  the replica  value is set to 1 by default. This means that only one Pod is deployed per application defined. To increase the performance and processing power of your deployment, you can increase  the replica  value for some application such as tsApp. You can also customize the resource allocation by modifying the  resources  definition for each application.

Persisting search data

It is recommended to mount persistent storage volumes within your search containers to allow HCL Commerce applications to persist data. If you do not set up persistent storage, the search index that is stored inside of the Docker container is lost if the container is stopped or restarted for any reason.

The following containers should have persistent storage configured, based on the search solution utilized:

Solr-based search solution:
- searchAppMaster
- searchAppRepeater
Elasticsearch-based search solution:
- nifiApp
- elasticsearch

To mount a storage volume, create a persistent volume claim in Kubernetes and match it to the corresponding application. Repeat this creation process for each application that requires persistent storage.

Create a yaml file with the following definitions.

For the purpose of this example, this file will be called pvc.yaml.

apiVersion: v1 
  kind: PersistentVolumeClaim 
  metadata: 
    name: <pvc name, e.g demoqa-nifi-pvc> 
    namespace: <namespace, e.g commerce>
  spec: 
    accessModes: 
    - ReadWriteOnce 
    resources: 
      requests: 
        storage: 10Gi 
    storageClassName: <storage class name, e.g standard for gke>

Create the persistent volume claim based on your yaml file definition.
Run the following command to load the file: kubectl apply -f pvc.yaml.
The persistent volume claim is created.
Match the application with its persistent volume claim.
Configure the deployment persistentVolumeClaim parameter value for the application and persistent volume claim pairing.

Migrating HCL Commerce from an older 9.1.`x` or 9.0.`x` release to a newer version of 9.1.`x`

When upgrading an existing deployment from an older HCL Commerce Version 9.0 or HCL Commerce Version 9.1 release to a newer release, there are some considerations that might be required.


Parameter	Description
backwardCompatibility.selector	The pod selector labels defined in the existing deployment. This is required when you deployed HCL Commerce using a different Helm Chart previously and want to use this Chart to upgrade.
backwardCompatibility.ingressFormatUpgrade.enable	Some NGINX and GKE ingress names have changed since the HCL Commerce 9.1.7.0 release. When upgrading from a version prior to 9.1.7.0 to a version that is 9.1.15.0 or greater, you must enable this parameter to trigger an upgrade job to clean up older ingress definitions and avoid conflicts during the upgrade.

In previously provided Helm Charts for HCL Commerce Version 9.0.x.x, the deployment matches the following labels to select Pods:

app (WCSV9)
chart ({{ .Chart.Name }}, For example, ibm-websphere-commerce)
release ({{ .Release.Name }}, For example, demo-qa-auth)
heritage ({{ .Release.Service }}, For example, Helm)
component ({{ .Values.common.tenant }}{{ .Values.common.environmentName}}{{ .Values.common.environmentType }}{{.Values.xxApp.name}}, For example, demoqaauthcrs-app)
group ({{ .Values.common.tenant }}{{ .Values.common.environmentName}}{{ .Values.common.environmentType }}, For example, demoqaauth)

In this Helm Chart example, the application and chart values are updated. This would cause Helm upgrade to fail as the LabelSelector is immutable. To upgrade a Version 9.0.x.x deployment to a Version 9.1.x.x using this Chart without downtime, specify the backwardCompatibility.selector to match the existing deployment.

For example:

backwardCompatibility: 
  selector: 
    ## In the Version 9.0.x.x Helm Chart, app is specified as WCSV9 by default 
    app: WCSV9

## In the Version 9.0.x.x Helm Chart, chart is specified as ibm-websphere-commerce by default  
    chart: ibm-websphere-commerce

For new deployment, keep backwardCompatibility.selector as an empty map.

backwardCompatibility: 
  selector: {}

Upgrading HCL Commerce from root to non-root images

When upgrading an existing deployment from using the root user to the non-root user, comuser, for the first time, you must review and carefully consider the following Helm Chart parameters.


Parameter	Description
Common.runAsNonRoot.enabled	This parameter starts all containers as the non-root user, `comuser`, to improve overall deployment security. Accepted values are: `true` to start containers as the non-root user. `false` to start containers as the root user. By default, this value is set to `true`. It is only recommended to disable this feature to continue using an existing deployment before it can be tested and updated for use with the non-root user. For more information, see HCL Commerce container users and privileges.
Common.runAsNonRoot.migrateAssetsPvcFromRootToNonroot	This parameter triggers a pre-upgrade job to update the permissions of the files within your Assets Tool `readWriteMany` Persistent Volume Container (PVC), if you use one within your existing deployment. This must be used in specific circumstances when upgrading your deployment to function correctly with the non-root user. For more information, see Updating PVC file permissions for upgrading a Kuberetes deployment from root to non-root user images.