Planning your container deployment using Helm
Helm is a software package manager that simplifies deployment of applications and services to Red Hat OpenShift and Kubernetes container platforms.
- Before proceeding with your HCL DX 9.5 deployment using Helm, review the
following Help Center topics:
- Deploying HCL DX CF196 to container platforms using Helm for an understanding of the capabilities, deployment structures, configuration and scaling options available for HCL DX 9.5 CF196 and later deployments.
- Containerization requirements and limitations for an understanding of the requirements, including capacity planning, and current limitations for an HCL Digital Experience 9.5 Container Update CF196 and later deployment using Helm.
- Prepare your HCL DX 9.5 target environment.
This section outlines mandatory and optional tasks that need to be done before installation of the HCL Digital Experience 9.5 Container Update CF196 to Google Kubernetes Engine using Helm. Support to deploy to Red Hat OpenShift, Amazon Elastic Kubernetes Service (Amazon EKS), and Microsoft Azure Kubernetes Service (AKS) using Helm is added in Container Update CF197.
This includes preparing your cluster to have proper access to application container images, creating a custom configuration file that fits your deployment needs and configuring network and application settings to allow your HCL Digital Experience 9.5 CF196 and later deployment to work properly.
- Mandatory tasks:The following tasks are mandatory for HCL Digital Experience 9.5 Container deployment to operate in your Kubernetes cluster using Helm.
- Prepare a namespace.
Before you can deploy HCL Digital Experience, it is recommended that you create a namespace inside your Kubernetes Cluster.
You need to create a namespace in your Kubernetes cluster that contains all the resources related to your HCL DX 9.5 Container deployment. It is recommended that this is created before deployment as you may need to add an ImagePullSecret or configure the TLS certificate for the Ambassador Ingress before deployment.
Identify a name for your namespace and create it using the following syntax:
- On Kubernetes
platformsKubectl
# Command to create a namespace using kubectl # This example creates a namespace called "my-namespace" kubectl create ns my-namespace
- OpenShift
For OpenShift, you must create a namespace with specific settings.
Use the following namespace definition and save it as namespace.yaml. You must replace
my-namespace
in the template with the name of the namespace you are using.apiVersion: v1 kind: Namespace metadata: name: my-namespace annotations: openshift.io/sa.scc.mcs: "s0:c24,c4" openshift.io/sa.scc.supplemental-groups: "1001/10000" openshift.io/sa.scc.uid-range: "1000/10000"
OpenShift client
# Command to create namespace from template file oc apply -f namespace.yaml
- On Kubernetes
platforms
- Prepare the Helm deployment configuration file.Create a configuration file that fits the needs of your target HCL DX 9.5 Container deployment. The configuration file is the heart of your deployment using Helm. It defines how HCL Digital Experience 9.5 is deployed to supported platforms, and how it behaves during runtime operations. This section explains how to create your own configuration file and how to leverage the existing
values.yaml
inside the Helm Chart. It also explains how to optionally overwrite settings in case the default set may not be sufficient.Important: Modification to any files (chart.yaml, templates, crds) in hcl-dx-deployment-vX.X.X_XXXXXXXX-XXXX.tar.gz, except custom-values.yaml or values.yaml, is not supported.- The configuration flow
- Helm provides multiple ways to define values that can be processed to run an installation. Processing involves a three-step approach, that is ordered sequentially within a hierarchy.
- Helm Chart
values.yaml
- Every Helm Chart contains a
values.yaml
file. It defines all configurable parameters that a Helm Chart accepts and the default values that are used during an installation. If you do not provide any other configuration during an installation, Helm extracts all deployment information from thevalues.yaml
file inside the Helm Chart.All parameters that were not overwritten using any other configuration methods return to their default values from the
values.yaml
file inside the Helm Chart. - Custom value files
- Helm provides you with a way to maintain your own custom values files. You
can specify a custom values file you want to use when running an
installation.This custom values file only needs to contain the parameters that you want to overwrite with your preferred settings.Note: There is no need to have the same complete set of parameters inside your custom values file, as there are available by default in the Helm Chart
values.yaml
. As outlined previously in this section, everything that is not defined in your custom values file are applied using the defaults fromvalues.yaml
inside the Helm Charts.Please be aware that the parameters you can configure using your custom values file need to exactly align with those provided by the Helm Charts own values.yaml. You cannot configure anything that is not exposed in the values.yaml definition.
- Override parameters
- It is possible to define values using a --set parameter
in the Helm CLI during the installation of a Helm Chart.
Since there are many values that can be configured in the HCL Digital Experience deployment, we do not recommend this technique, since it makes installation commands very large and confusing.
- The default HCL DX 9.5 Container
values.yaml
file - HCL DX 9.5 Helm Chart provides a default values.yaml,
which contains all possible configuration parameters.To access this file, you may use the following command when you have the HCL DX 9.5 CF196 or later Helm Chart tar.gz file on hand:
# Command to extract values.ymal from Helm Chart helm show values hcl-dx-deployment.tar.gz > values.yaml
The file contains all configurable parameters and their default values. You may use this file as a blueprint to create your owncustom-values.yaml
. You may also just rename the extractedvalues.yaml
tocustom-values.yaml
.Note: Having a complete copy of the defaultvalues.yaml
is not necessary and may bloat your configuration file with values that are already present in the DX Helm Chart. - A custom configuration file
- Helm allows you to provide a custom configuration file during the
installation or upgrade process.
That file only overwrites settings that are defined within it. For parts of the configuration that are not defined in your custom configuration file, Helm returns to the default values in the
values.yaml
file inside the DX Helm Chart.This allows you to create a file that only overwrites settings that are required, keeping the overall size of your configuration file small and the maintainability high.
This Help Center documentation refers to the custom configuration file as
custom-values.yaml
. You may name your custom configuration file as preferred.
- Load container images.
This section presents how to load the DX 9.5 Container Update CF196 or later images into your container image repository, tag them to fit your repository structure, and push them to your repository, so that all Nodes in your Kubernetes or OpenShift cluster can deploy HCL Digital Experience 9.5 Pods.
To use HCL Digital Experience 9.5 in your Kubernetes or OpenShift cluster, you have to make the container images available to all nodes of your cluster. Usually this is done by providing them through a container image repository.
Depending on your cloud provider, there may be different types of default container image repositories already configured. Refer to the documentation of your cloud provider for setup and use of such platform container image repository.
It is assumed that you have a repository configured and running, and is technically reachable from all your Kubernetes or OpenShift cluster nodes.
In the following guidance, the docker CLI is used as a command reference. Tools like Podman may also be used, but are not described in this documentation. The procedure for the use of such tools are the same.
- Extract HCL Digital Experience 9.5 package.The HCL Digital Experience 9.5 Container Update packages are provided in a compressed .zip file, that can easily be unzipped using a utility of your choice. Refer to the latest HCL DX 9.5 Container Update Release CF196 and later file listings in the Docker deployment topic:Note: The following are examples using Container Update CF196 files. Replace those references with the HCL DX 9.5 Container Update CFxxx release files you are deploying.
# Unzip of HCL Digital Experience 9.5 CFxxx package unzip hcl-dx-kubernetes-v95-CF196.zip
The package includes all DX 9.5 container images, and Helm Charts as tar.gz files.
The content of the package looks similar to the following structure:hcl-dx-kubernetes-v95-CF196.zip HCL DX notices V9.5 CF196.txt # Notices file dx-dx-ambassador-image-154.tar.gz # Image for the Ambassador Ingress hcl-dx-cloud-operator-image-v95_CFXXX_XXXXXXXX-XXXX.tar.gz # Image for the Core Operator (not needed for Helm deployments) hcl-dx-cloud-scripts-v95_CFXXX_XXXXXXXX-XXXX.zip # Cloud deployment scripts incl. dxctl (not needed for Helm deployments) hcl-dx-content-composer-image-vX.X.X_XXXXXXXX-XXXX.tar.gz # Image for Content Composer hcl-dx-core-image-v95_CFXXX_XXXXXXXX-XXXX.tar.gz # Image for Core hcl-dx-digital-asset-management-operator-image-v95_CFXXX_XXXXXXXX-XXXX.tar.gz # Image for the Digital Asset Management Operator (not needed for Helm deployments) hcl-dx-digital-asset-manager-image-vX.X.X_XXXXXXXX-XXXX.tar.gz # Image for Digital Asset Management hcl-dx-experience-api-sample-ui-vX.X.X.XXXXXXXX-XXXX.zip # Sample UI for Experience API hcl-dx-image-processor-image-vX.X.X_XXXXXXXX-XXXX.tar.gz # Image for Image Processor hcl-dx-openldap-image-v1.1.0-master_XXXXXXXX_XXXXXXXXXX.tar.gz # Image for OpenLDAP hcl-dx-postgres-image-vX.X.X_XXXXXXXX-XXXX.tar.gz # Image for Digital Asset Management Persistence hcl-dx-redis-image-X.X.X.tar.gz # Image for Ambassador Ingress Redis hcl-dx-remote-search-image-v95_CFXXX_XXXXXXXX-XXXX.tar.gz # Image for Remote Search hcl-dx-ringapi-image-vX.X.X_XXXXXXXX-XXXX.tar.gz # Image for Ring API hcl-dx-runtime-controller-image-vX.X.X_XXXXXXXX-XXX.tar.gz # Image for Runtime Controller hcl-dx-deployment-vX.X.X_XXXXXXXX-XXX.tar.gz # Helm Charts
- Load images locally.To load the individual image files, you may use the following command:
# Command to load container image into local repository # docker load < image-file-name.tar.gz docker load < hcl-dx-core-image-v95_CFXXX_XXXXXXXX-XXXX.tar.gz
If you want to load all DX 9.5 CFxxx image files via one command, you may use the following command:# Command to load all images at once # Since HCL Digital Experience images are all containing the word "images", # we can filter for fitting tar.gz files ls -f | grep image | xargs -L 1 docker load -i
This loads all images to your local repository, ready for further usage.
You may verify if the loading is successful with the following command:# List all images docker images # Command output (minified, example) REPOSITORY TAG IMAGE ID CREATED SIZE hcl/dx/remote-search v95_CF195_20210514-1708 e4c46618f404 4 weeks ago 2.25GB hcl/dx/cloud-operator v95_CF195_20210515-0201 62cc304706a3 4 weeks ago 220MB hcl/dx/core v95_CF195_20210514-1708 36e30c620cdd 4 weeks ago 6.29GB hcl/dx/openldap v1.1.0-master_20210514_1621013302 a5519e06dd17 4 weeks ago 772MB hcl/dx/image-processor v1.8.0_20210514-1712 d5d99d86f81a 4 weeks ago 507MB hcl/dx/digital-asset-manager v1.8.0_20210514-1711 19c8b76b1cad 4 weeks ago 547MB hcl/dx/digital-asset-management-operator v95_CF195_20210514-1714 bc0f5638817a 4 weeks ago 218MB hcl/dx/content-composer v1.8.0_20210514-1707 62b7b54d3895 4 weeks ago 427MB hcl/dx/postgres v1.8.0_20210514-1708 d94672f395ad 4 weeks ago 498MB hcl/dx/ringapi v1.8.0_20210514-1709 505eebb52ebf 4 weeks ago 397MB
- Re-tag images.
If you are using a Kubernetes cluster that is not configured to operate on your local machine, you may need to push the HCL Digital Experience 9.5 container images to a remote repository.
To do so, you need to re-tag the images to point to your remote repository.Important Note: Do not change the version tags of the DX 9.5 images, as they are used for uniquely identifying which versions of DX applications are running in your cluster.You may re-tag any image using the following command:# Re-tag an existing loaded image # docker tag OLD_IMAGE_PATH:VERSION NEW_IMAGE_TAG:VERSION # Example command for DX Core: docker tag hcl/dx/core:v95_CF195_20210514-1708 my/test/repository/hcl/dx/core:v95_CF195_20210514-1708
If you want to prefix all HCL Digital Experience 9.5 container images with your repository structure, you may use the following command:# Command to prefix all HCL Digital Experience container images # export the prefix for the repository structure, without tailing slash export REMOTE_REPO_PREFIX="my/test/repository" # First we list all HCL Digital Experience 9.5 Images, then we remove the first line containing the header # Then we execute the docker tag command, prefixing each image with the $REMOTE_REPO_PREFIX docker images hcl/dx/* | tail -n +2 | awk -F ' ' '{system("docker tag " $1 ":" $2 " $REMOTE_REPO_PREFIX/" $1 ":" $2) }'
The output may be verified by using the following command:# List all images docker images # Command output (minified, example) REPOSITORY TAG IMAGE ID CREATED SIZE hcl/dx/remote-search v95_CF195_20210514-1708 e4c46618f404 4 weeks ago 2.25GB my/test/repository/hcl/dx/remote-search v95_CF195_20210514-1708 e4c46618f404 4 weeks ago 2.25 hcl/dx/cloud-operator v95_CF195_20210515-0201 62cc304706a3 4 weeks ago 220MB my/test/repository/hcl/dx/cloud-operator v95_CF195_20210515-0201 62cc304706a3 4 weeks ago 220MB hcl/dx/core v95_CF195_20210514-1708 36e30c620cdd 4 weeks ago 6.29GB my/test/repository/hcl/dx/core v95_CF195_20210514-1708 6e30c620cdd 4 weeks ago 6.29GB hcl/dx/openldap v1.1.0-master_20210514_1621013302 a5519e06dd17 4 weeks ago 772MB my/test/repository/hcl/dx/openldap v1.1.0-master_20210514_1621013302 a5519e06dd17 4 weeks ago 772MB hcl/dx/image-processor v1.8.0_20210514-1712 d5d99d86f81a 4 weeks ago 507MB my/test/repository/hcl/dx/image-processor v1.8.0_20210514-1712 d5d99d86f81a 4 weeks ago 507MB hcl/dx/digital-asset-manager v1.8.0_20210514-1711 19c8b76b1cad 4 weeks ago 547MB my/test/repository/hcl/dx/digital-asset-manager v1.8.0_20210514-1711 19c8b76b1cad 4 weeks ago 547MB hcl/dx/digital-asset-management-operator v95_CF195_20210514-1714 bc0f5638817a 4 weeks ago 218MB my/test/repository/hcl/dx/digital-asset-management-operator v95_CF195_20210514-1714 bc0f5638817a 4 weeks ago 218MB my/test/repository/hcl/dx/content-composer v1.8.0_20210514-1707 62b7b54d3895 4 weeks ago 427MB hcl/dx/content-composer v1.8.0_20210514-1707 62b7b54d3895 4 weeks ago 427MB hcl/dx/postgres v1.8.0_20210514-1708 d94672f395ad 4 weeks ago 498MB my/test/repository/hcl/dx/postgres v1.8.0_20210514-1708 d94672f395ad 4 weeks ago 498MB hcl/dx/ringapi v1.8.0_20210514-1709 505eebb52ebf 4 weeks ago 397MB my/test/repository/hcl/dx/ringapi v1.8.0_20210514-1709 505eebb52ebf 4 weeks ago 397MB
- Push to repository.You may use the following command to push the container images to your repository:
# Push the new tagged images # docker push NEW_IMAGE_TAG:VERSION # Example command for core: docker push my/test/repository/hcl/dx/core:v95_CF195_20210514-1708
If you want to push all your locally processed images, you may use the following command:# Command to push all HCL Digital Experience images to a remote repository # export the prefix for the repository structure, without tailing slash export REMOTE_REPO_PREFIX="my/test/repository" # Push the images, first we filter for the ones necessary # Second we execute a docker push for each image docker images $REMOTE_REPO_PREFIX/hcl/dx/* | awk -F ' ' '{system("docker push " $1 ":" $2)}'
After running this command, Docker goes ahead and pushes the images to your remote repository. After the push, the container images are now ready for use by your Kubernetes or OpenShift cluster.
- Adjust deployment configuration.
After you have successfully prepared all DX 9.5 images, you need to configure the images inside your custom-values.yaml.
The following syntax may be used to define the correct image configuration for your environment:Note: If deploying to a Hybrid environment, with DX 9.5 Container Update CF198 or later, the Core needs to be set as false, since Core is already installed to an On-premise Server.# Fill in the values fitting to your configuration # Ensure to use the correct image version tags images: repository: "my/test/repository" # Image tag for each application tags: contentComposer: "v95_CFXXX_XXXXXXXX-XXXX" core: "v95_CFXXX_XXXXXXXX-XXXX" designStudio: "vX.X.X_XXXXXXXX-XXXX" digitalAssetManagement: "vX.X.X_XXXXXXXX-XXXX" imageProcessor: "vX.X.X_XXXXXXXX-XXXX" openLdap: "vX.X.X_XXXXXXXX-XXXX" persistence: "vX.X.X_XXXXXXXX-XXXX" remoteSearch: "v95_CFXXX_XXXXXXXX-XXXX" ringApi: "vX.X.X_XXXXXXXX-XXXX" ambassadorIngress: "vX.X.X_XXXXXXXX-XXXX" ambassadorRedis: "vX.X.X_XXXXXXXX-XXXX" runtimeController: "vX.X.X_XXXXXXXX-XXXX" # Image name for each application names: contentComposer: "hcl/dx/content-composer" core: "hcl/dx/core" designStudio: "hcl/dx/design-studio" digitalAssetManagement: "hcl/dx/digital-asset-manager" imageProcessor: "hcl/dx/image-processor" openLdap: "hcl/dx/openldap" persistence: "hcl/dx/postgres" remoteSearch: "hcl/dx/remote-search" ringApi: "hcl/dx/ringapi" ambassadorIngress: "hcl/dx/ambassador" ambassadorRedis: "hcl/dx/redis" runtimeController: "hcl/dx/runtime-controller"
- Additional tasks:
If your remote repository requires access credentials, it is necessary to configure an
ImagePullSecret
to allow your cluster nodes to have proper access to the HCL DX 9.5 container images.Please refer to Configure Networking topic for instructions on how to configure this.
- Prepare a namespace.
Refer to PersistentVolumeClaims (PVCs) for the next steps.