Deploy DX Container to Microsoft Azure Kubernetes Service (AKS)

Learn how to deploy HCL WebSphere Portal (DX) 9.5 CF_182 and higher container release along with Ambassador to Kubernetes, as verified in Microsoft Azure Kubernetes Service (AKS).

Prerequisites

Prior to using the procedure below, it is assumed that the HCL DX Administrator is generally experienced in using Kubernetes. Additionally, the DX Administrator must have the appropriate access to the target environment. If not, following are some preliminary steps that need to be taken.

• Setup KUBECONFIG to refer to the target server. This will ensure any kubectl commands executed locally affect the target environment.

• Use kubectl get {pods, pv, storageclass} to get appropriate information from the artifacts running in the target Kubernetes environment.

Follow these steps to deploy HCL WebSphere Portal 9.5 CF_182 and higher container release along with Ambassador to Kubernetes, as verified in Microsoft Azure Kubernetes Service (AKS). This deployment relies heavily on Kubernetes Operators for full functionality.

Note: Reference the latest HCL DX 9.5 Container Release and Update file listings in the Docker deployment topic.

Deployment

1. Download and extract the contents of the HCL DX 9.5 CF_182 package to the local file system.

   

2. In Microsoft Azure Kubernetes Service (AKS), load, tag, and push the HCL Digital Experience images into your MS Azure Container Registries.

   Note: In Microsoft Azure, when using AKS a single Container Registry, or multiple Container Registries may be used. See theMicrosoft Azure Container Registry documentation for additional information about this topic.In this example, 10 Container Registries are created:

   

   As an alternative, DX Administrators can use a single or fewer registries and create 'Repositories' within. In this example, a Container Registry named azambassador with a repository 'ambassador' is shown:

   

   Administrators can tag and push another image into this Container Registry to get a second repository.

   

   In the following example, the Ambassador Redis image is added:

   

   The HCL DX 9.5 Container deployment does not assume 1, or many registries are defined, and either definition setup will work. In the following example, the HCL DX 9.5 Redis 5.0.1 image is added to the azambassador Container Registry. This example shows loading the HCL DX 9.5 CF_182 and higher container into a local repository, tagging it and pushing it to the azuredxen Container Registry in the dxen 'Repository'.

   

Install the HCL WebSphere Portal 9.5 CF_182 or higher core images

1. Load the HCL DX 9.5 CF_182 or higher images to your deployment. The following example uses the CF_183 version in the load command:

   Docker load -I hcl-dx-core-image-v95_CF183_20200819-1159.tar.gz

   

2. Docker tag and docker push to the Azure environment:

   

   Once complete, the image will be viewable in the Microsoft Azure repository:

   

   Reminder : Consult the HCL WebSphere Portal 9.5 Deployment - Docker topic for the latest list of HCL DX 9.5 Container files available. HCL DX 9.5 Container Update CF_183 files are used in these examples:

   CF183-core.zip files

   • HCL DX notices V9.5 CF183.txt
   • hcl-dx-ambassador-image-154.tar.gz
   • hcl-dx-cloud-operator-image-v95_CF183_20200818-1852.tar.gz
   • hcl-dx-cloud-scripts-v95_CF183_20200818-1852.zip
   • hcl-dx-core-image-v95_CF183_20200818-1342.tar.gz
   • hcl-dx-redis-image-5.0.1.tar.gz

   CF183-other.zip files

   • HCL DX notices V9.5 CF183.txt
   • hcl-dx-content-composer-image-v1.2.0_20200818-1343.tar.gz
   • hcl-dx-digital-asset-management-operator-image-v95_CF183_20200818-1344.tar.gz
   • hcl-dx-digital-asset-manager-image-v1.2.0_20200818-1346.tar.gz
   • hcl-dx-image-processor-image-v1.2.0_20200818-1345.tar.gz
   • hcl-dx-openldap-image-v1.0.0-master_20200818_1597758965.tar.gz
   • hcl-dx-postgres-image-v1.2.0_20200818-1349.tar.gz
   • hcl-dx-remote-search-image-v95_CF183_20200818-1342.tar.gz
   • hcl-dx-ringapi-image-v1.2.0_20200818-1351.tar.gz

   To install HCL DX 9.5 core software to Microsoft Azure AKS, the following images are required:

   • hcl-dx-cloud-operator-image-v95
   • hcl-dx-core-image-v95
   • hcl-dx-ambassador-image
   • hcl-dx-redis-image

   Images included in the 'other' package are optional and used to support use of OpenLDAP, Remote Search, the Experience API, Content Composer, and Digital Asset Management components and services.

   See examples that show how to load HCL DX 9.5 images to MS Azure below.In the following example the items are loaded into the azuredxen Content Registry and multiple repositories are created. Images are tagged with dx-183 reflecting the HCL DX 9.5 Container Update CF_183 version images used in this deployment.

   

3. At this stage, the ./deploy/operator.yaml needs to be properly updated and the operator, and Redis image details need to be provided:

   1. First, replace the line:

      From: 'image: REPOSITORY_NAME /hcldx-cloud-operator:9.5.next'

      To: Add the proper value for the deployment, as in the following example:

      'image: azuredxen.azurecr.io/hcldx-cloud-operator:v95_CF183_20200819-1711'

   2. Next, replace the values: "REDIS_REPO","REDIS_IMG_ENV",'REDIS_TAG_ENV' with proper values. See the following example:

      

   3. Reviewing the Azure dashboard, administrators can see the following for redis:

      

4. Deploy the Custom Resource Definition using the scripts/deployCrd.sh file. See the following example:

   

   Important : Ensure there is an available persistent volume for the deployment or a self-provisioning storage class. The HCL DX Help Center topic (Sample Storage Class and Volume for HCL WebSphere Portal 9.5 Container Deployments) can be referenced for related guidance. In this example, a storage class named dx-deploy-stg and a volume dxdeployhave been created:

   

5. Run the deployment scripts as follows:

   ./scripts/deployDx.sh az-demo 1 azuredxen.azurecr.io dxen v95_CF183_20200819-1159 dxeploy dx-deploy-stg derby ambassador 154

   • NAMESPACE - the project or the namespace to create or use for deployment.
   • REPLICAS - the number of initial instances for the deployment.
   • REPOSITORY - your local repository, the repository used by Kubernetes.
   • IMAGENAME - the name of the dxCore image, as added to the repository above.
   • IMAGETAG - the tag for the target image as added to the repository above.
   • VOLUMENAME - the volume to be used by the deployment for persistence, this must use AccessMode ReadWriteMany .
   • STORAGECLASS - the storage class name used to create the persistent volume.
   • DBTYPE - the database type. By default, and initially, this is Derby. HCL DX 9.5 uses Apache Derby, Oracle Database, DB2, or Microsoft SQL Server. Acceptable values are derby, oracle, db2, or msSql.
   • INGRESSIMAGE - The image name to use for Ambassador.
   • INGRESSTAG - The image tag to use for Ambassador.

   The command output shows the values as they align with the deployment, and the result of each step.DX Administrators can use 'kubectl get pods -n az-emo' to check the pods as they are starting. See the following example:

   

   

6. While waiting for the pods to start up DX Administrators must create a tls secret for ambassador as follows:

   kubectl create secret tls dx-tls-cert --cert=my-cert.pem --key=my-key.pem -n aws-mynamespace

   

   In this example, an existing key and certification created using openssl was used.

   • Use SSL, administrators can create a private key: 'openssl genrsa -out my-key.pem 2048'
   • Use OpenSSL, administrators can create a certificate signed by the private key: 'openssl req -x509 -key my-key.pem -out my-cert.pem -days 365 -subj '/CN=my-cert'

   At this stage, the deployment will write out the wp_profile into the persistent volume, and configure HCL DX 9.5 a minimum default configuration. See the HCL DX 9.5 Container Requirements and Customization topics for additional information.

7. Once the HCL DX 9.5 dx-deployment-0 pod is running, administrators can access the HCL DX 9.5 deployment by obtaining the ambassador service details. Command examples to obtain this information:
   • 'kubectl get svc -n az-demo' or
   • 'kubectl get svc ambassador -n az-demo'

     

8. Use the external IP address obtained via the kubectl get command (https://external-ip/wps/portal ), select the resulting URL obtained to access the HCL DX 9.5 deployment.

   

   Note: It is required to ensure the MS Azure AKS load balancer configured permits external access. Consult the MS Azure documentation for Load Balancer setup and default configuration details.

(Optional) Deploy the OpenLDAP, Experience API, Content Composer, and Digital Asset Management components to Microsoft AKS

1. Create a config map with the same name as the dx statefulset used to deploy the HCL DX 9.5 CF_182 and higher Core image software. By default, the dx statefulset is dx-deployment, as shown in this example:

   

   kubectl create configmap dx-deployment -n az-demo

   

2. Once created, populate it with the following data:

   data:
   
     dx.deploy.openldap.enabled: 'true'
     dx.deploy.openldap.tag: dx-183
     dx.deploy.openldap.image: dx-openldap
     dx.deploy.experienceapi.enabled: 'true'
     dx.deploy.experienceapi.tag: dx-183
     dx.deploy.experienceapi.image: ring-api
     dx.deploy.contentui.enabled: 'true'
     dx.deploy.contentui.tag: dx-183
     dx.deploy.contentui.image: content-ui
     dx.deploy.dam.enabled: 'true'
     dx.deploy.dam.volume: releaseml
     dx.deploy.dam.storageclass: dx-deploy-stg
     dx.deploy.dam.persistence.tag: dx-183
     dx.deploy.dam.persistence.image: persist
     dx.deploy.dam.imgprocessor.tag: dx-183
     dx.deploy.dam.imgprocessor.image: image-processor
     dx.deploy.dam.tag: dx-183
     dx.deploy.dam.image: dam
     dx.deploy.dam.operator.tag: dx-183
     dx.deploy.dam.operator.image: hcl-dam-operator
     dx.deploy.host.override: 'false'
   

   Administrators can also create the config map in a yaml file and deploy it with the following instructions (example): kubectl create -f my_config_map.yaml -n az-demo.

3. After creating the config map, the HCL DX 9.5 CF_182 and higher deployment will go into 'init' mode, and restart a couple of times after the new options are configured. Administrators can check the status via the command line using the command (example) kubectl get pods -n az-demo:

   

   As an alternative approach, administrators can check the status of the deployment progress through the MS Azure AKS dashboard:

   

4. In this deployment of HCL DX 9.5 core and optional images, the DX core image will be the last container to start successful. Note that it will restart twice.

5. Once restarts are complete, administrators can confirm the deployment and configuration of the DX core and OpenLDAP, Experience API, Content Composer, and Digital Asset Management images as follows:

   OpenLDAP image deployment validation:

   1. Navigate to Practitioner Studio > Administration > Security > Users and Groups , and search for all available groups:

      

      The group ldap_test_users should appear in this listing.

   2. To validate the Content Composer and Experience API image deployments, navigate to Practitioner Studio > Web Content > Content Composer :

      

   3. To validate the Digital Asset Management and Experience API image deployments, navigate to Practitioner Studio > Digital Assets :

      

   4. To validate access to the Experience API, administrators and developers should be able to access the Experience API at the following URL:

      https://external-ip/dx/api/core/v1/explorer/

   See the following section for additional information:
   • Install Experience API, Content Composer, and Digital Asset Management

Update the HCL WebSphere Portal 9.5 Azure AKS deployment

1. To update the deployment, run the updateDx.sh script with updated values:

   ./scripts/updateDx.sh NAMESPACE REPLICAS REPOSITORY IMAGENAME IMAGETAG VOLUMENAME STORAGECLASS DBTYPE INGRESSIMAGE INGRESSTAG

   • NAMESPACE - the project or the namespace to create or use for deployment.
   • REPLICAS - the number of initial instances for the deployment.
   • REPOSITORY - your local repository, the repository used by Kubernetes.
   • IMAGENAME - the name of the dxCore image, as added to the repository above.
   • IMAGETAG - the tag for the target image as added to the repository above.
   • VOLUMENAME - the volume to be used by the deployment for persistence, this must use AccessMode ReadWriteMany .
   • STORAGECLASS - the storage class name used to create the persistent volume.
   • DBTYPE - the database type. By default, and initially, this is Derby. HCL DX 9.5 uses Apache Derby, Oracle Database, DB2, or Microsoft SQL Server. Acceptable values are derby, oracle, db2, or msSql.
   • INGRESSIMAGE - The image name to use for Ambassador (Native K8s).
   • INGRESSTAG - The image tag to use for Ambassador (Native K8s).For example:

     ./scripts/UpdateDx.sh az-demo 1 azuredxen.azurecr.io dxen v95_CF183_20200819-1159 dxeploy dx-deploy-stg derby ambassador 154

     

2. Once the database is transferred, the DBTYPE will need to be updated so we can scale the instances higher. Additionally, once the database is transferred, the number of replicas could be increased.

   See the Customize the Kubernetes deployment topic for more information on customizing your deployment.

Delete the HCL WebSphere Portal 9.5 Azure AKS deployment

1. Remove the entire deployment requires several steps, this is by design.

   • To remove the deployment in a specific namespace, run the removeDx.sh script:

     ./scripts/removeDx.sh NAMESPACE 

     • NAMESPACE - the project or the namespace created or used for deployment.

2. To remove a namespace, use any of the following commands:
   • Kubernetes command:

     'kubectl delete -f dxNameSpace_NAMESPACE .yaml'

     where NAMESPACE is the namespace to be removed

3. The persistent volume associated to the deployment needs to be cleaned up by your Administrator. To reuse a persistent volume, see the following steps:

   • Open the persistent volume in a visual editor (vi) using the
     • Kubernetes command:

       kubectl edit pv <pv_name>

   • Remove the claimRef section:

     claimRef:
        apiVersion: v1
        kind: PersistentVolumeClaim
        name: dx-deploy-pvc
        namespace: az-demo
        resourceVersion: "488931120"
        uid: ebd58361-0e2a-11ea-b02e-02f8fe687954

   • Ensure you get the 'persistentvolume/<pv_name> edited' message.

   • You may need to manually remove any data remaining from the previous deployment.

Parent topic: Deployment