Installation

This section provides instructions for installing the HCL Cloud Native Link application on a Kubernetes cluster using the official Helm chart.

Before you begin

Before installing the Helm chart, complete the following steps.

  1. Configure Helm to Access hclcr.io

    Log in to the HCL Harbor OCI registry (hclcr.io) to pull the Helm chart.

    helm registry login hclcr.io --username [my-email-address] --password [my-harbor-cli-secret]

    Where [my-email-address] is the user's email address for the Harboot OCI registry, and [my-harbor-cli-secret] is the corresponding secret.

  2. Pull the Helm Chart

    Download the chart from the OCI registry.

    For example, run the following command to pull the chart for version 8.1.5:

    helm pull oci://hclcr.io/link/lnk-product --version 8.1.5
    This command downloads a .tgz file (for example, lnk-product-8.1.5.tgz) to your current directory.
  3. Create an Image Pull Secret

    Create a docker-registry secret in your target namespace so Kubernetes can pull the Link images from hclcr.io.

    The helm install examples refer to this secret as hclcr-secret.

    kubectl create secret docker-registry hclcr-secret \
  --docker-server=hclcr.io \
  --docker-username=[my-email-address] \
  --docker-password=[my-harbor-cli-secret] \
  --namespace <your-namespace>
  4. Prepare Volumes (Optional)

    If you need persistent storage (recommended for production), ensure a StorageClass exists in your cluster.

    The chart will use this to provision PersistentVolumeClaims (PVCs).

    Specify the StorageClass during installation using the global.storageClass parameter:

  5. Prepare MongoDB and Redis (Optional)

    The chart includes MongoDB and Redis as sub-charts for quick setup. However, it is highly recommended to use external, managed instances of MongoDB and Redis for production environments..

    If you use external instances, you must disable the bundled charts and provide your external connection details via Helm overrides. For example, mongodb.enabled=false, redis.enabled=false, and setting external connection strings.

  6. Create Unica Integration Secret (If Applicable)
    IIf you are integrating Link with HCL Unica, create the primary user secret before the Link installation using the following command:
    kubectl create secret generic hcl-unicaui-login-secret --from-literal=password=password

    Replace password with the actual Unica admin password.

About this task

The installation is managed using the helm install command.

Procedure

  1. Run Helm Install:

    Install the chart using the .tgz file downloaded earlier. To configure the installation, use the --set flag for quick overrides or a custom values.yaml file for detailed configuration.

    Option 1: Standalone Link Installation

    This example shows a standalone installation using the overrides provided in the reference.

    helm install <releaseName> ./lnk-product-<version>.tgz \
--set global.hclImageRegistry="hclcr.io" \
--set global.hclImagePullSecret="hclcr-secret" \
--set global.storageClass="link-storage-class" \
--set client.image.tag="1.3.0.1-fix-20250310112959" \
--set client.inbound.protocol="https" \
--set client.outbound.server.protocol="https" \
--set client.headers.crossOriginAllowedUrls="" \
--set server.image.tag="1.3.0.1-fix-20250310112959" \
--set server.persistence.data.shareWithRest=true \
--set server.inbound.http.enabled=false \
--set server.inbound.https.enabled=true \
--set rest.image.tag="1.3.0.1-fix-20250310112959" \
--set rest.inbound.http.enabled=true \
--set rest.inbound.https.enabled=true \
--set executor.image.tag="1.3.0.1-fix-20250310112959"

    Option 2: Link with Unica Integration

    This example uses Unica-specific images and enables the Unica integration flags.
    helm install <releaseName> ./lnk-product-<version>.tgz \
--set global.hclImageRegistry="gcr.io/blackjack-209019" \
--set global.hclImagePullSecret="gcr-secret" \
--set global.storageClass="" \
--set client.image.tag="1.3.0.1-unica-fix-20250310112959" \
--set client.inbound.protocol="https" \
--set client.outbound.server.protocol="https" \
--set client.headers.crossOriginAllowedUrls="http://njmyclddl313111.nonprod.hclpnp.com" \
--set server.image.tag="1.3.0.1-unica-fix-20250310112959" \
--set server.persistence.data.shareWithRest=true \
--set server.inbound.http.enabled=false \
--set server.inbound.https.enabled=true \
--set rest.image.tag="1.3.0.1-unica-fix-20250310112959" \
--set rest.inbound.http.enabled=true \
--set rest.inbound.https.enabled=true \
--set executor.image.tag="1.3.0.1-unica-fix-20250310112959" \
--set kafkaLink.deploy=true \
--set kafkaLink.image.tag="1.3.0.1-unica-fix-20250310112959" \
--set kafkaLink.kafkaBroker.externalName="10.134.69.243:9092" \
--set customConnectors.enabled=true \
--set unicaIntegration.enabled=true \
--set unicaIntegration.unicapvc="hcl-unica" \
--set unicaIntegration.releaseName="hcl" \
--set unicaIntegration.initialUnicaLogin.secret="hcl-unicaui-login-secret"
  2. Helm Override Options

    You can provide configuration overrides in two ways:

    Using --set: Useful for changing a few values.

    --set client.image.tag="<new-tag>"

    Using a values.yaml file :This is the recommended method for complex or production deployments.

    1. Inspect the default values.yaml from the chart: 
      tar -xvf lnk-product-<version>.tgz
cat lnk-product/values.yaml > my-custom-values.yaml
    2. Edit my-custom-values.yaml with all your changes.
    3. Install using the -f flag: 
      helm install <releaseName> ./lnk-product-<version>.tgz -f my-custom-values.yaml

Pods are stuck in ImagePullBackOff or ErrImagePull

Cause: The image pull secret (global.hclImagePullSecret) is missing, incorrect, or not in the correct namespace.

Fix: Run kubectl describe pod <pod-name> -n <namespace> to identify the exact error. Verify the secret exists (kubectl get secret hclcr-secret) and that the credentials are correct.

Pods stuck in Pending

Cause: The cluster has insufficient resources (CPU or memory), or a PersistentVolumeClaim (PVC) cannot be bound.

Fix: Run kubectl describe pod <pod-name> and check the Events section for messages such as insufficient cpu or failed to bind volume. Ensure the global.storageClass value matches an available StorageClass.

Problem: Pods in CrashLoopBackOff

Cause: The application starts and then fails due to configuration errors such as incorrect MongoDB/Redis credentials or a missing secret.

Fix: Check logs using kubectl logs <pod-name> -n <namespace> and review for fatal or connection errors.

What to do next

After the helm install command succeeds, complete the following steps to verify and access the application.

  1. Retrieve the Auto-Generated Password

    The Helm chart generates a default administrator password and stores it in a Kubernetes secret. The secret name and key are available in the chart’s README.md or values.yaml file.

    kubectl get secret <releaseName>-admin-secret -n <namespace> -o jsonpath="{.data.password}" | base64 --decode
    Note: The secret name (<releaseName>-admin-secret) is an example. Check the chart documentation for the actual secret name.

  2. Access the Link UI

    The Link application can be accessed using one of the following methods:

    Method 1:Port Forwarding (For Testing)
    • Use kubectl port-forward to connect to the client service.
      kubectl get secret <releaseName>-admin-secret -n <namespace> -o jsonpath="{.data.password}" | base64 --decode
      Note: The secret name (<releaseName>-admin-secret) is an example. Check the chart documentation for the actual secret name.

    • Access the UI at: https://localhost:4443

    Method 2: Ingress (Recommended)

    • For persistent access, configure an Ingress resource. Ensure an Ingress Controller (for example, NGINX) is running in the cluster.

      For example, link-ingress.yaml:

      apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: link-ingress
  annotations:
    nginx.ingress.kubernetes.io/use-regex: "true"
    nginx.ingress.kubernetes.io/rewrite-target: /$1
spec:
  ingressClassName: nginx
  rules:
  - host: mynode.local
    http:
      paths:
      - path: /restdemo/(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: <releaseName>-lnk-product-rest
            port:
              number: 8080
      - path: /serverdemo/(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: <releaseName>-lnk-product-server
            port:
              number: 8080
      - path: /(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: <releaseName>-lnk-product-client
            port:
              number: 80

    • Apply it with kubectl apply -f link-ingress.yaml -n <namespace>.

  3. Verify the Installation

    Check the status of all Kubernetes objects created by the release.

    Check Pods – Ensure all pods are in the Running state.
    kubectl get pods -n <namespace> -l app.kubernetes.io/instance=<releaseName>
    Check Services – Verify that all services are created and assigned CLUSTER-IPs.
    kubectl get svc -n <namespace> -l app.kubernetes.io/instance=<releaseName>
    Check Volumes (if enabled) – Confirm that all PVCs are in the Bound state.
    kubectl get pvc -n <namespace> -l app.kubernetes.io/instance=<releaseName>

    Log in to the Link UI – Use the password retrieved in Step 1 to sign in via Port Forward or the Ingress URL.