Deploying HCL Commerce+ with Helm on Kubernetes

Commerce+ supports several deployment configurations. The default configuration mode the provided Helm Chart uses is Vault configuration mode.

Vault is the configuration management tool for Commerce+as it was designed to store configuration data securely. Commerce+ also uses Vault as a Certificate Authority to issue certificates to each application to communicate with one another securely. Therefore, ensure that you have a Vault service available for the Commerce to access. The following steps highlight the minimum requirements before deploying Commerce+.

A complete Commerce+ environment is composed of an authoring (auth) environment , (live) environment and a shared (share) environment.

Authoring (auth): For site administration and business users to make changes to the site.
Live (live): For shopper-facing storefront access.
Shared (share): Contains the applications that can be consumed by both auth and live environment .

For non-production environments, you can consider the use of hcl-commerce-vault-helmchart to deploy and initialize Vault for Commerce+ as it can initialize the Vault and populate data for Commerce+. However, that chart runs Vault in development and non-high availability (HA) mode and does not handle a Vault token securely. Therefore, it should not be used for production environments. You can read Vault Concepts for all considerations that must be made to run Vault in a production setting.

Important:

The environment that you create should not be used for a live production site without further consideration toward security hardening, load balancing, ingress routing, and performance tuning.. To operate Commerce+ in a live production environment, you must commit further time and resources to both performance and security considerations.

With load balancing and ingress routing specifically, you can configure which services you want to expose externally, and restrict the remaining services within the cluster network. This configuration limits their access from and exposure to the wider Internet.

Before you begin

Ensure that you have deployed Vault. Vault is a mandatory component that is used by default as a Certificate Agent to automatically issue certificates, as well as to store and retrieve essential deployment configuration variables and secrets. For more information, see Configuring your Commerce+ environment using Vault
Ensure that your environment is prepared. To set up the appropriate environment, see Preparing your Commerce+ environment.

Procedure

Deploy Supporting Services
You can deploy the supporting services separately from Commerce+ instead of deploying them together with the Commerce+ Helm chart.
- Elasticsearch-based search: Deploy Elasticsearch, ZooKeeper, and Redis.
- Solr-based search: Deploy Redis.
Optional: If you want to deploy Zookeeper and Redis separately from a Commerce+ (instead of deploying together), you can follow the following steps.
Important:
- Enable persistence for Elasticsearch, ZooKeeper, and Redis to ensure that search indexes and connector configurations are retained if the containers are restarted.
- Deploy ZooKeeper and Redis by using the Helm chart versions that are compatible with your Commerce+ Helm chart. The required chart versions are specified in the hcl-commerce-helmchart/stable/hcl-commerce/Chart.yaml file in your cloned Commerce+ Helm chart repository. Ensure that the --version parameter in the deployment commands matches the version specified in this file.
1. Deploy Elasticsearch. (Elasticsearch-based search only)
  
  Deploy an Elasticsearch 9 cluster by using Elastic Cloud on Kubernetes (ECK).
  1. Install the ECK operator.
```
helm repo add elastic https://helm.elastic.co
helm repo update
helm install elastic-operator elastic/eck-operator  -n elastic-system --create-namespace
```
  2. (Optional) Create a namespace for Elasticsearch.
```
kubectl create namespace elastic-apps
```
  3. Create an elasticsearch.yaml manifest file.
    Configure the manifest to disable Elasticsearch security because the current Commerce+ Elasticsearch-based search supports HTTP connections only. A sample elasticsearch.yaml file is available in the hcl-commerce-helmchart/sample_values directory.
  4. Deploy Elasticsearch.
```
kubectl apply -f elasticsearch.yaml -n elastic-apps
```
  5. Monitor the deployment status until all pods are healthy and the cluster accepts traffic:
```
kubectl get pods -n elastic-apps
kubectl exec -it elastic-apps-es-master-data-0 -n elastic-apps -- \
curl http://localhost:9200/_cluster/health?pretty
```
  For more information, see the Elasticsearch documentation to deploy an Elasticsearch 9 cluster.
  - Install the ECK Operator
  - Deploy Elasticsearch
2. Deploy Zookeeper.
  1. Create a namespace.
```
kubectl create ns zookeeper
```
  2. Add the Helm Chart repository.
```
helm repo add bitnami https://charts.bitnami.com/bitnami
```
  3. Deploy ZooKeeper by using the zookeeper-values.yaml configuration file.
    A copy of this file can be found in the sample_values directory of your cloned Commerce+ Helm Chart Git project.
```
helm install my-zookeeper bitnami/zookeeper -n zookeeper -f zookeeper-values.yaml --version="zookeeper-chart-version"
```
  4. Monitor the deployment and ensure that all pods are healthy.
  For more information about deploying Zookeeper with Helm, see The Zookeeper Helm Chart documentation.
3. Deploy Redis.
  1. Create a namespace for Redis.
```
kubectl create ns redis
```
  2. Add the Helm Chart repository.
```
helm repo add bitnami https://charts.bitnami.com/bitnami
```
  3. Deploy Redis using a local redis-values.yaml file.
    A sample version of this file is available in the sample_values directory of your cloned Commerce+ Helm Chart Git project.
    helm install my-redis bitnami/redis -n redis -f redis-values.yaml --version="redis-chart-version"
  4. Monitor the deployment and ensure that all pods are healthy.
  For more information about deploying Redis with Helm, see the Redis Helm Chart documentation.
Configure Persistent Storage

Required components like NiFi, and the database (PostgreSQL). Use ReadWriteMany (RWX) volumes for multi-pod access (for example, AssetsPVC) and ReadWriteOnce (RWO) for the database.

For more information, see Enabling persistent storage.
Configure your Commerce+ deployment Helm Chart.
Use the provided hcl-commerce-helmchart to customize your deployment. Review the following topics based on your configuration knowledge and requirements:
Note: 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.
Customize the values.yaml(for example, my-values.yaml) to define:
- Environment types (auth, live, share).
- Storage classes or PVCs for persistence.
- Vault integration settings (for example, token, secrets path).
- For customers upgrading from HCL Commerce Version 9.1 to Commerce+, see Migrating from HCL Commerce Version 9.1 to HCL Commerce+.
Use Helm to control the deployment of Commerce+.
Once you have finished the configuration of your deployment in your my-values.yaml file and meet the environment prerequisites, you are ready to deploy Commerce+ by using Helm.
Important:
- Deploy the auth, live, and share groups into the same Kubernetes namespace to avoid any potential issues.
- First time deployment
  1. Deploy the share group with release name demo-qa-share into the commerce namespace.
    helm install demo-qa-share hcl-commerce-helmchart -f my-values.yaml --set common.environmentType=share -n commerce
  2. Deploy the auth group with the release name demo-qa-auth into the commerce namespace.
    helm install demo-qa-auth hcl-commerce-helmchart -f my-values.yaml --set common.environmentType=auth -n commerce
  3. Deploy the live group with the release name demo-qa-live into the commerce namespace.
    helm install demo-qa-live hcl-commerce-helmchart -f my-values.yaml --set common.environmentType=live -n commerce
  Once the Commerce+ applications are deployed, if you have further configuration changes or image updates, you can use the Helm upgrade command to update the deployment.
- Updating a deployment
  To update a deployment run the following Helm command for the release and environmentType that you want to update.
```
helm upgrade release-name hcl-commerce-helmchart -f my-values.yaml --set common.environmentType=environmentType -n commerce
```
  Note:
  
  There are several considerations when upgrading your deployment with regards to the Assets Tool and its persisted storage configuration:
  
  Instead of using commercenfs in the values.yaml configuration file to create the NFS storageclass, it is recommended to create an NFS storageclass manually. Creating a storageclass manually will avoid issues that can be encountered when running the helm upgrade command when deploying separate environment types within a single namespace.
  To create an NFS storageclass, see nfs-server-provisioner.
  
  If you use the Elasticsearch-based search solution, it is required to use a completely new persistent volume for NiFi, and clear any existing Zookeeper data before you redeploy. This is required so that the newer version of the connectors can be created automatically during the deployment.
  
  To clear the NiFi data:
  
  See Persisting search data to create a new Persistent Volume Claim (PVC), and configure the new PVC name in your deployment values.yaml file.
  
  You can then remove the previous attached persistent volume claim.
  kubectl delete pvc previous_pvc_name -n commerce
  
  To clear Zookeeper data:
  
  Delete the existing Zookeeper instance.
  helm delete my-zookeeper -n zookeeper
  
  Remove the existing persistent volume claims.
  kubectl delete pvc --all -n zookeeper
  
  Then, follow step 1.b.iii to re-deploy Zookeeper.
  
  HCL Cache caches classes that can be modified in newer versions of Commerce+. To avoid errors in de-serializing an old version of the class, it is strongly recommended to clear Redis keys after upgrading Commerce+. Redis keys can be cleared with the Redis flushdb or flushall commands.
  
  Once you upgrade Commerce+, recreate any customized search profiles and connectors before your next search indexing.
- Removing a deployment
  To uninstall or delete a deployment run the following Helm command for the release that you want to remove.
```
helm delete release-name
```
Observe the deployment.
When you install or update Commerce+, the start-up must follow a precise sequence. The Support Container is primarily used for service dependency checks, to ensure that the various Commerce applications are brought online properly, and in the expected order. In addition, it is also used by some utility jobs, such as for TLS certificate generation for secure ingress. The deployment process can take up to 10 minutes depending on the capacity of your Kubernetes worker nodes.
You can check the status of your deployment. The following values are displayed in the Status column.
- Running: This container is started.
- Init: 0/1: This container is pending on another container to start.
You can also observe the following values displayed in the Ready column:
- 0/1: This container is started but the application is not yet ready.
- 1/1: This application is ready to use.
Build your search index.
- With the Elasticsearch-based search solution:
  1. Trigger the Build Index job.
```
curl -X POST -k -u spiuser:plain_text_spiuser_password https://tsapp-demoqaauth.mycompany.com/wcs/resources/admin/index/dataImport/build?connectorId=auth.reindex&storeId=41
```
    A response with a jobStatusId is displayed.
  2. Check the Build Index job status using the jobStatusId value that was returned.
```
curl -X GET -u spiuser:plain_text_spiuser_password https://tsapp-demoqaauth.mycompany.com/wcs/resources/admin/index/dataImport/status?jobStatusId=jobStatusId -k
```
    A returned value of 0 indicates that the build completed successfully.
Access your environments.
By default, the Helm Chart uses the default values of tenant, env, and envtype. If you changed the default values, update the host names that are used within the following step examples.
1. Check the gateway IP address.
```
kubectl get gateway -n commerce
```
2. Get the gateway httproute hostname.
```
kubectl get httproute -n commerce
```
3. Create the gateway IP and hostname mapping by editing your development environment hosts file.
```
#Auth environment
<Gateway_IP>  www-demoqaauth.mycompany.com cmc-demoqaauth.mycompany.com tsapp-demoqaauth.mycompany.com store-preview-demoqaauth.mycompany.com store-demoqaauth.mycompany.com
```
```
#Live environment
<Gateway_IP>  www-demoqalive.mycompany.com cmc-demoqalive.mycompany.com tsapp-demoqalive.mycompany.com store-preview-demoqalive.mycompany.com store-demoqalive.mycompany.com
```
4. Access your environment pages and tools with following URLs:
  - A Ruby storefront : https://www-demoqaauth.mycompany.com?storeId=41 or https://www-demoqaauth.mycompany.com/ruby
  - A Ruby B2B storefront : https://www-demoqaauth.mycompany.com?storeId=42 or https://www-demoqaauth.mycompany.com/rubyb2b
  - Commerce Lab (Tooling): https://tooling-demoqa.mycompany.com/tooling/login
  - Commerce Lab for HCL Commerce+: https://cmc-demoqa.mycompany.com/lobtools/cmc/ManagementCenter
  - Auroraesite: https://store-demoqaauth.mycompany.com/wcs/shop/en/auroraesite
  - Aurorab2besite: https://store-demoqaauth.mycompany.com/wcs/shop/en/aurorab2besite
  Certificate Requirements:
  - For the production environment, a valid certificate must be used.
  - For dev or QA environment, if a valid certificate is not used, you will need to accept certificate warnings when accessing the environment from a browser.
  For example, to access the tooling URL, users must accept the certificate warnings by opening each of the following URLs in their web browser:
  - https://cmc-demoqaauth.mycompany.com/lobtools/tooling-configurations/transaction-config.json
  - https://cmc-demoqalive.mycompany.com/lobtools/tooling-configurations/transaction-config.json
  Note: For the Preview Store button in tooling, if you encounter this message: The webpage at https://store-preview-demoqaauth.hclcdev.com/Ruby?storeId=41&WCPreviewToken=KieqlKqZqqGqk6pL0p8IRw&newPreviewSession=true might be temporarily down or may have moved permanently to a new web address. Then you need to open the given URL in a separate browser tab and accept the warning.

Results

Your Commerce+ Kubernetes deployment is now complete.