Prerequisites for deploying HCL Commerce on a Kubernetes cluster

There are multiple software, environment, and deployment configuration prerequisites to deploy HCL Commerce on Kubernetes. HCL Commerce provides a large degree of flexibility, and each available option should be considered for viability in your resulting production deployment.

The default configuration mode used by the provided Helm Chart is  the Vault  configuration mode. Vault is also the recommended configuration mode for HCL Commerce, as Vault is designed to store configuration data securely. In addition to storing configuration data, Vault is also used by HCL Commerce as a Certificate Authority, to issue certificates to each application in order to communicate with one another securely.

For non-production environments, you can consider the use of the hcl-commerce-vaultconsul-helmchart Helm Chart to deploy and initialize Vault for HCL Commerce. However, this chart runs Vault in development mode, not high availability (HA) mode. It also does not handle the Vault token securely. Therefore, it should not be used for production environments. See Vault Concepts in the Vault documentation for more considerations for running Vault in a production setting.


  1. Obtain the HCL Commerce Helm Charts.

    HCL Commerce Version or laterBeginning with HCL Commerce, a Power Linux version of the Helm Chart is included for use on that platform. Ensure that you are using the correct version of the Helm Chart for the platform that you are deploying to.

    1. Review Downloading HCL Commerce software and The list of the latest available download packages to ensure that you are obtaining the most up-to-date version of HCL Commerce software.
    2. Download and extract the latest version of the HCL Commerce Helm chart Git bundle (HCL_Commerce_Helm_Charts_9.1.x.x.bundle).
    3. Clone the repository.
      git clone bundleName projectName
      The filename of the bundle you are cloning.
      The name of the git project that you are creating.
      For example:
      git clone HCL_Commerce_Helm_Charts_9.1.x.x.bundle HCL_Commerce_Helm_charts
  2. Vault-Consul is a mandatory component that is used by default as a Certificate Agent to automatically issue certificates.
    It is also used as a configuration center for the deployment to store environment-related data. Ensure that you have completed deploying Vault-Consul. For more information and instructions on deploying Vault-Consul for use with HCL Commerce, see Deploying a development Vault for HCL Commerce on Kubernetes.
    HCL Commerce Version or laterNote: Consul and all related configurations were removed from HCL Commerce and greater. The filename of the provided Vault Helm Chart, however, remains the same.
  3. You require a Kubernetes cluster to deploy HCL Commerce.
    It is recommended that you use Kubernetes 1.16 or greater.

    It can be on a private or public cloud, or even on a Kubernetes cluster that is set up with kubeadm. For more information about using kubeadm, see Creating a single master cluster with kubeadm.

    By default, when you use the provided Helm Chart to deploy HCL Commerce Version 9, you begin with the following number of Pods and required resources:

    Component Replica Request CPU Limit CPU Request Memory Limit Memory
    ts-app 1 500m 2 4096Mi 5120Mi
    ts-db 1 2000m 2 4096Mi 6144Mi
    ts-web 1 500m 2 2048Mi 4096Mi
    search-app-master 1 500m 2 2048Mi 4096Mi
    search-app-repeater (live) 1 500m 2 2048Mi 4096Mi
    search-app-slave (live) 1 500m 2 2048Mi 4096Mi
    crs-app 1 500m 2 2048Mi 4096Mi
    xc-app 1 500m 2 2048Mi 4096Mi
    tooling-web 1 500m 2 1024Mi 2048Mi
    store-web 1 500m 2 1024Mi 2048Mi
    nifi-app 1 500m 2 6144Mi 10240Mi
    registry-app 1 500m 2 1024Mi 2048Mi
    ingest-app 1 500m 2 2048Mi 4096Mi
    query-app 1 500m 2 2048Mi 4096Mi
    HCL Commerce Version or latermustgather-app 1 500m 1 2048Mi 4096Mi
    HCL Commerce Version or laterts-utils 1 500m 2 2048Mi 4096Mi
    HCL Commerce Version or latergraphql-app 1 500m 2 2048Mi 2048Mi
    HCL Commerce Version or laterapproval-app 1 500m 2 2048Mi 2048Mi

    Ensure that your cluster has sufficient resources for your deployment. The requirements outlined below are only an estimate. They are based on a full environment (auth, live and shared groups) deployment with a single instance (replica set) for each application. These numbers also include the 10 vCPUs and 12GB of memory overhead requirement that are utilized in a rolling upgrade scenario. During an upgrade multiple instances of an application can be active at the same time.

    The expected resources that are required are based on the search solution that is used in the deployment:
    Search solution vCPUs Memory
    Solr-based search solution 40 68 GB
    Elasticsearch-based search solution 48 82 GB
    • The Elasticsearch Natural Language Processing (NLP) feature can consume large amounts of memory in NiFi with multiple languages enabled. For example, with two languages enabled, Nifi can use up to 10GB of memory. Ensure that adequate memory is allocated to Nifi for your deployment needs.
    • For a detailed breakdown on the suggested minimum Kubernetes resource requirements for a variety of deployment topologies, see HCL Commerce Kubernetes deployment resource planning.
  4. You require an ingress controller to access HCL Commerce once it is deployed on Kubernetes.

    The HCL Commerce Helm Chart primarily supports the use of the Nginx ingress controller. To set up the Nginx ingress controller on your Kubernetes cluster, see the Installation Guide in the Nginx ingress documentation.

    Additional ingress controller support is available within the HCL Commerce Helm Chart, with restrictions depending on your deployment and the version of HCL Commerce that is used:
    • Support for the use of GCE ingress is available when deploying HCL Commerce on Google Kubernetes Engine (GKE).
    • Ambassador Edge Stack ingress is supported with a version of Kubernetes below 1.22.
      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 or greater.
    • HCL Commerce Version or laterSupport for Red Hat OpenShift routes.
    • HCL Commerce Version or laterSupport for Emissary 2.x (Emissary-ingress).
  5. You require Helm to manage the application on Kubernetes.
    It is recommended to use Helm version 3.0.1 or greater. To download and set up Helm, visit
  6. A Vault token must be stored as a secret object.
    This value is also placed in your Helm chart values to allow the HCL Commerce application to consume the Vault token value. If you use hcl-commerce-vaultconsul-helmchart to deploy vault for development or non-production usage, a secret named vault-token-secret should have been created already in the commerce namespace in step 2.d of Deploying a development Vault for HCL Commerce on Kubernetes. Otherwise, complete the following steps to create a new secret and import it into your environment.
    1. Obtain the base64 encoded string of your vault token by passing it through the base64 system utility. In a command prompt, run echo -n vault_token | base64.
    2. Create a file named vault-secret.yaml with the following content. Replace <VAULT_TOKEN> to the value obtained, and replace <NAME_SPACE> to commerce. Save the file.
      apiVersion: v1 
      kind: Secret 
        name: vault-token-secret 
        namespace: <NAME_SPACE>
      type: Opaque 
    3. Run kubectl apply -f vault-secret.yaml to create the secret within the commerce namespace.
  7. All Docker images that are required for the HCL Commerce deployment must be loaded to a Docker Registry where your Kubernetes cluster can access them.

    You can obtain the HCL Commerce from the HCL License and Delivery portal. For up to date release information, see HCL Commerce eAssemblies.

    The tags that are used in your Docker Registry must be the same as those used in your Helm Charts.

  8. One or more databases are required.
    For quick testing or exploratory purposes, you can use the HCL Commerce sample DB2 database Docker image, which has the default schema and sample bootstrap data loaded, to explore HCL Commerce features and functionality. However, it is strongly recommended to set up your database on its own dedicated server so that you can persist data and tune performance. Database sizing requirements will vary by vendor and configuration. See Setup prerequisites for an HCL Commerce production environment for more information on the requirements for an HCL Commerce production environment.

    HCL Commerce Version or laterWith the introduction of the Approval service for use within a Marketplace, a PostgreSQL database is also required to be deployed.

  9. Role Based Access Control (RBAC) must be created beforehand, and only once on the target namespace.
    The remaining steps in this deployment assume that HCL Commerce is deployed on the commerce namespace. Perform the following steps as a cluster administrator.
    1. If you have not already created the commerce namespace, such as in the prerequisites of Deploying a development Vault for HCL Commerce on Kubernetes, create it now by running the following command: kubectl create namespace commerce.
      HCL Commerce Version or laterNote: The following steps, 9.b and 9.c, can be skipped from HCL Commerce onward. This is because from this point the HCL Commerce Helm Chart creates the RBAC rules automatically during the deployment.
    2. Modify  the rbac.yaml  file by replacing  <namespace>  with commerce.
    3. Run the following command to apply the RBAC: kubectl apply -f rbac.yaml.
    Important: Some Cloud platforms, such as IBM Cloud, require a PodSecurityPolicy (PSP) to be bound to the target namespace prior to installation. Choose a predefined PSP or have your cluster administrator set up a custom PSP for you. For IBM Cloud, choose the ibm-privileged-psp for the least restrictive policy, or refer to the IBM Cloud Pak PodSecurityPolicy Definitions to learn more.
    The cluster administrator can either use the above PSP and ClusterRole definitions into the create resource screen of the user interface, or run the following two commands:
    • kubectl create -f <PSP_yaml_file>

    • kubectl create clusterrole commerce-psp-clusterrole --verb=use --resource=podsecuritypolicy --resource-name=commerce-psp

    In IBM Cloud Private 3.1, you must create the RoleBinding by running the following command:
    • kubectl create rolebinding commerce-psp-rolebinding --clusterrole=commerce-psp-clusterrole --serviceaccount=commerce:default --namespace=commerce
    In IBM Cloud Private 3.1.1+, you must create the RoleBinding by running the following command:
    • kubectl create rolebinding ibm-psp-rolebinding --clusterrole=ibm-privileged-clusterrole --serviceaccount=commerce:default --namespace=commerce
  10. Optional: HCL Commerce Version or later Enable the Assets tool.

    If you intend for the Assets Tool to be used within your deployment, you must implement accessible persistent storage.

    To implement persistent storage, see Setting up persistent storage volumes for a Kubernetes deployment.

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

  11. Optional: HCL Commerce Version or later Disable Tooling analytics.

    To disable Tooling analytics:
    • If you use Vault in your deployment, set the Vault allowTelemetry key value to no prior to deployment.
    • Set the Tooling Web Docker container ALLOW_TELEMETRY container environment variable to no on deployment.


Your environment is now prepared. You can now deploy HCL Commerce. Continue with Deploying HCL Commerce on a Kubernetes cluster.