Required Helm Chart configuration for Commerce+

The following reference provides a more detailed look at the provided hcl-commerce-helmchart Helm Chart, and the various configuration options and considerations that are essential for a custom deployment of Commerce+ on Kubernetes.

It is strongly recommended to not modify the default  values.yaml configuration  file for your deployment. Instead create a copy to use as your customized values file, for example, my-values.yaml. This will allow you to maintain your customized values for future deployments and upgrades.

The following configuration considerations should be reviewed:

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 Commerce+. To view the license, browse all of the files under the LICENSES directory.

To accept the license, set  license  to  accept.
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.
common.tenant
  • The common.tenant value can be your organization name. You can have multiple environments under the same tenant.
common.environmentName
  • The common.environmentName is the name of the environment. Some examples of environment name are dev, qa or production. Each Commerce+ environment can be used to partition logical groups of different hosted applications.
common.environmentType
  • The common.environmentType is the specific environment type. For each environment, an environment type must be specified:
    • auth holds the 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.searchEngine The Search solution. Accepted values are:
  • Solr for the Commerce+ Solr-based search solution
  • elasticfor the HCL Commerce Elastic Search-based search solution.
common.vaultTokenSecret The name of the secret object which contains the Vault token. Refer to Deploying a development Vault for Commerce+ and Prerequisites for deploying Commerce+ on a Kubernetes cluster to understand how the Vault token is passed to Commerce+.
common.dbType The type of database that the environment is using.
Valid values are:
  • db2 for IBM Db2.
  • oracle for Oracle.
  • postgres for PostgreSQL.
common.imageRepo The Docker image 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 Commerce+.
common.spiUserPwdAes The spiuser user password, encrypted with AES by the wcs_encrypt utility.
The default plain text password is :
  • TxV9uCk6URiwvSVaa4odD94jaKi2za8ssjneSWdu7vgKHd, which when encrypted corresponds with the default key, opsKG7t6iFVptA+z7JUKe+JQJgOXfDkZUUpiUMS1hJZL9hYK3ymSQ2ssVDoz+SToaC/H3g+g+9RGcLejkI/KpPLI5Q+=.
You can use the default key to match the sample postgres database Docker container.

For more information, see Configuring the spiuser password for Commerce+ Kubernetes Deployment.
common.spiUserPwdBase64 The Base64 encoded value for  spiuser:password.
The default plain text password is:
  • FyxsV9uCk6URiwvPVaa9wdD66jaHi2za5ssjnfJMdu3vIqi, or  c6BpdYNlcjpReFY3dUNrNlJSaXd2UFhhYTR+3ZEQ3OGphHTkyemE6c7NqbmVOTWR+1M3ZncjK= 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-.vault.svc.cluster.local:8200/v1

Note: This value assumes that hcl-commerce-vault-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.bindingConfigMap The name of the ConfigMap that is to be mounted into each container to expose environment variables. Leave this value blank if you are not using a ConfigMap to pass configuration to each application.
common.configureMode Commerce+ supports only Vault 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.ipv6Enabled

The parameter to enable IPV6.

When disabled, Commerce+ applications adds the java.net.preferIPv4Stack=true JVM parameter, and use IPv4.

Accepted values are true, to enable IPv6, and false to use IPv4.
vaultCA.enabled

The parameter to enable Vault as a Certificate Authority to issue certificates. The default value is true.

HCL Cache and Metrics and Service monitor configuration values

Parameter Description
hclCache.configMap The ConfigMap that is used for HCL Cache definition.
metrics.enabled The parameter to enable metrics for Commerce+.

The default for this parameter is true.
metrics.prometheusAnnotations.enabled

The parameter to add Prometheus scraping annotations to pods.

Accepted values are:
  • true to enable Prometheus scraping annotations.
  • false to not enable Prometheus scraping annotations.
metrics.serviceMonitor.enabled The parameter to enable service monitoring with Prometheus.

The default for this parameter is false.
metrics.serviceMonitor.interval The interval, in seconds, to allow Prometheus to query HCL Commerce for service monitoring.
metrics.serviceMonitor.selector.prometheus The labels for Prometheus to match for service monitoring.

Open Telemetry configuration

Parameter Description
openTelemetry.javaAgentEnabled Enable Open Telemetry Java Agent
openTelemetry.javaAgentJarVersion Open Telemetry Java Agent version, the current version is 2.7.0. If you want to use a different version, use this configuration to specify the version.
openTelemetry.javaAgentJarDownloadUrl The url to be used to download OpenTelemetry Java Agent JAR. This configuration is required when using the specified openTelemetry.javaAgentJarVersion.
openTelemetry.exporterOtlpEndpointEnabled

When there is no OTLP exporter endpoint, or when you do not want to configure or enable exporters,

Set the value to false to disable exporters for telemetry data, and /SETUP/otel/otel_noexporters.properties will be used for the configuration.
openTelemetry.configMap

ConfigMap for OpenTelemetry java agent configure file.

Configuration file name will be otel_config.properties and mounted to /SETUP/otel/config

Leave any properties with variable substitutions untouched, and those will be set automatically.

Some other optional environment variables that are already defined in the templates including
 ${OTEL_K8S_NAMESPACE}, ${OTEL_K8S_POD_UID}, ${OTEL_K8S_POD_NAME}
, and you can add those based on your requirements.
openTelemetry.nextjsOtelEnabled Opentelemetry enablement for nextjs server. Next.js server is not using Java, and therefore Java related configration under openTelemetry will be ignored. Properties defined under Opentelemetry.configMap will be configured as environment variables in Next.js server.

Search index job configuration

When the Elastic-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.

Parameter Description
searchIndexCreation.enabled The parameter to enable an Elastic-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.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.
July, 2026 release or later

Gateway configuration

The Kubernetes Gateway API provides external access to applications that are deployed in a Kubernetes cluster. The Commerce+ Helm Chart uses the Kubernetes Gateway API (gateway.networking.k8s.io/v1) with Istio as the gateway controller, replacing the legacy Ingress resource.

The Gateway configuration defines routing rules for commonly used Commerce+ services, such as Commerce Lab and the storefront. For each service, you can configure the domain name and TLS secret for both the authoring and live environments. You can use the Gateway configuration that is provided by the Commerce+ Helm Chart or customize the Gateway manifests to meet your deployment requirements.

Parameter Description
gateway.enabled Enables Gateway resource creation. Accepted values are true to enable the gateway and false to disable it.
gateway.type Specifies the gateway controller type. Supported value: istio.
gateway.gatewayClass.name Specifies the name of the GatewayClass resource that is used by the Gateway. Template expressions are supported.
gateway.gatewayClass.create Specifies whether to create the GatewayClass resource as part of the Helm deployment. Set to true to create the resource. Set to false if the gateway provider, such as Istio, already creates the GatewayClass resource.
gateway.gatewayClass.controllerName Specifies the controller name for the GatewayClass resource. The default value for Istio is istio.io/gateway-controller.
gateway.serviceAnnotations Specifies annotations to add to the Gateway LoadBalancer Service. The default annotations are configured for Istio on Azure Kubernetes Service (AKS), where a health probe is required for Istio's health port (15021). On Google Kubernetes Engine (GKE) and Amazon Elastic Kubernetes Service (EKS), these annotations are ignored and can be set to {}.
gateway.backendTLSCAConfigMap Specifies the name of the Kubernetes ConfigMap that contains the backend CA certificate for the BackendTLSPolicy. If not specified, the default vault-backend-ca-cm-{envType} ConfigMap, which is created by the vault-fetch-ca-job, is used.
gateway.gatewaySecret.autoCreate Specifies whether Helm creates a TLS certificate secret during the pre-install phase. This option is useful for generating a self-signed certificate in test environments.
gateway.gatewaySecret.replaceExist Specifies whether an existing TLS certificate secret is replaced during deployment.
gateway.gatewaySecret.tlsSecret Specifies the name of an existing TLS secret for Gateway TLS termination. If not specified, the automatically generated TLS secret is used.
gateway.enableToolingForReactStore Specifies whether the Gateway route for the Marketplace Approval service is enabled.
gateway.<service>.auth.domain Specifies the domain name for the authoring environment of the specified service. Template expressions are supported.
gateway.<service>.live.domain Specifies the domain name for the live environment of the specified service. Template expressions are supported.
gateway.<service>.auth.tlsSecret Specifies the TLS secret for the authoring environment of the specified service. If not specified, the automatically generated TLS secret that matches the domain pattern is used.
gateway.<service>.live.tlsSecret Specifies the TLS secret for the live environment of the specified service. If not specified, the automatically generated TLS secret that matches the domain pattern is used.

Persistent volume for PV Asset

A persistent volume with ReadWriteMany access is created for inventory to store inventory data.

Parameter Description
commercenfs.enabled Non-production usage only to support RWX storage. Recommend to deploy separately in order to persist data when uninstalling theCommerce+ Helm Chart. For more details, see nfs-server-provisioner.
assetsPVC.enabled Create a Persistent Volume Claim (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.

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:
  • 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.
  1. 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>
  2. 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.

  3. Match the application with its persistent volume claim.

    Configure the deployment persistentVolumeClaim parameter value for the application and persistent volume claim pairing.