Deploying Litmus UNS on Kubernetes using Helm Chart

18min
You can deploy Litmus UNS on Kubernetes using a Helm chart. This chart initializes a Litmus UNS deployment on a Kubernetes cluster using the Helm package manager. 
Before You Begin
Have familiarity with Kubernetes and ensure you have Kubernetes version 1.25 or higher installed.
Have familiarity with Helm and ensure you have Helm version 3.8.0 or higher installed.
Quick Installation
Note: Create an order at the ﻿Litmus UNS homepage to obtain the Kubernetes pull secret from Litmus Automation.
Before installing Litmus UNS, submit the pull secret to the cluster using the following commands:
Shell
kubectl create namespace uns
kubectl create -f THE-SECRET_FILENAME --namespace=uns
kubectl create namespace uns
kubectl create -f THE-SECRET_FILENAME --namespace=uns
﻿
Now you can install the chart with the release name uns in the uns namespace and simultaneously create the namespace using the following command:
Shell
helm install uns oci://quay.io/litmusautomation/charts/litmus-uns --wait --namespace uns --set "imagePullSecrets[0].name=THE-SECRET-NAME"
helm install uns oci://quay.io/litmusautomation/charts/litmus-uns --wait --namespace uns --set "imagePullSecrets[0].name=THE-SECRET-NAME"
﻿
Replace THE-SECRET-NAME with the secret name from the file provided by Litmus. This command deploys Litmus UNS with the default configuration on your Kubernetes cluster.
Tip: 
Use helm list to display all releases. The Parameters section provides a list of configuration options available for installation.
To learn more about creating, editing, managing, or deleting Kubernetes Secrets, refer to the Managing Secrets using Kubectl guide.
Detailed Installation 
This section provides detailed instructions on how to configure and install Litmus UNS using Helm.
Step 1: Configure SSL Certificates for UNS
The Helm chart can configure SSL/TLS for the Litmus UNS service using Kubernetes secrets. Below are the steps and configurations for setting up SSL certificates.
Default SSL Certificate
By default, the Helm chart deploys a self-signed SSL certificate, which is stored in a Kubernetes secret and generated during the deployment process. 
The following parameters can be configured:
Secret Name: The Helm parameter luns.tlsSecretName specifies the name of the Kubernetes secret used for the SSL certificate.
Certificate Validity: The certificate's default Time To Live (TTL) is determined by luns.tls.ttl and is set to 390 days by default.
DNS and IP Configuration:
DNS Alternative Names: Configure using luns.tls.altNames with a default value of uns.local.
IP Addresses: The default IP is 127.0.0.1, configured through luns.tls.ipList.
Binding a Static IP to the SSL Certificate
To learn how to set up a static IP and associate it with a Load Balancer service in Azure, you can refer to the Azure manual. 
When using this Helm chart, you can define annotations for the Load Balancer service using the Helm parameter service.annotations.
Custom SSL Certificate
To use a custom SSL certificate, follow these steps:
1. Create a Kubernetes secret with your SSL certificate and private key: 
Shell
kubectl create secret generic ca-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt
kubectl create secret generic ca-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt
﻿
2. Update the Helm chart values to use the name of your new secret. You can do this by setting luns.tlsSecretName to the name of your created secret: 
Shell
helm upgrade -n [namespace] [release] [chart] --set luns.tlsSecretName=new-secret-name
helm upgrade -n [namespace] [release] [chart] --set luns.tlsSecretName=new-secret-name
﻿
For this guide, when using the release name uns in the uns namespace, the previously mentioned command should be adjusted as follows:
Shell
helm upgrade -n uns uns oci://quay.io/litmusautomation/charts/litmus-uns --set luns.tlsSecretName=new-secret-name
helm upgrade -n uns uns oci://quay.io/litmusautomation/charts/litmus-uns --set luns.tlsSecretName=new-secret-name
﻿
Step 2: Using External Database for UNS
The Helm chart deploys a PostgreSQL database server by default. However, you can also use a more reliable external database managed by a cloud provider like Google Cloud SQL.
External PostgreSQL Configuration
To use an external PostgreSQL database, set the following chart parameters:
YAML
postgres:
  enabled: false
  external:
    enabled: true
    host: "your-postgresql-host"
    port: 5432
    secretName: ext-db-creds
postgres:
  enabled: false
  external:
    enabled: true
    host: "your-postgresql-host"
    port: 5432
    secretName: ext-db-creds
﻿
Parameters:
host is the PostgreSQL database server hostname.
port is the PostgreSQL database server port.
secretName is the Kubernetes secret containing the database administrator credentials, which can be created with the following command: kubectl -n uns create secret generic ext-db-creds --from-literal=POSTGRES_USER='your-postgres-username' --from-literal=POSTGRES_PASSWORD='your-postgres-password'
Example: Google Cloud SQL Configuration
Note: Follow the Google Cloud SQL documentation to deploy an instance of Cloud SQL for PostgreSQL.
In this example, we will use the Cloud SQL Auth Proxy to set up a connection.
To configure cloud SQL auth proxy: 
1. Create a secret with the service account key for cloud SQL auth proxy: 
Shell
kubectl -n uns create secret generic cloud-sql-instance-credentials \
  --from-file=credentials.json=/path/to/your/service-account-key.json
kubectl -n uns create secret generic cloud-sql-instance-credentials \
  --from-file=credentials.json=/path/to/your/service-account-key.json
﻿
2. Create a file cloudsql-proxy.yaml with the following content, replacing GOOGLE_PROJECT:CLOUDSQL_ZONE:CLOUDSQL_INSTANCE with actual values:
YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cloudsql-proxy
  labels:
    app: cloudsql-proxy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cloudsql-proxy
  template:
    metadata:
      labels:
        app: cloudsql-proxy
    spec:
      containers:
      - name: cloudsql-proxy
        image: gcr.io/cloudsql-docker/gce-proxy:latest
        command: ["/cloud_sql_proxy",
                  "-instances=GOOGLE_PROJECT:CLOUDSQL_ZONE:CLOUDSQL_INSTANCE=tcp:0.0.0.0:5432",
                  "-credential_file=/secrets/cloudsql/credentials.json"]
        ports:
        - containerPort: 5432
        volumeMounts:
        - name: cloudsql-instance-credentials
          mountPath: /secrets/cloudsql
          readOnly: true
      volumes:
      - name: cloudsql-instance-credentials
        secret:
          secretName: cloud-sql-instance-credentials

---
apiVersion: v1
kind: Service
metadata:
  name: cloudsql-proxy
  labels:
    app: cloudsql-proxy
spec:
  type: ClusterIP
  ports:
  - port: 5432
    targetPort: 5432
  selector:
    app: cloudsql-proxy
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cloudsql-proxy
  labels:
    app: cloudsql-proxy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cloudsql-proxy
  template:
    metadata:
      labels:
        app: cloudsql-proxy
    spec:
      containers:
      - name: cloudsql-proxy
        image: gcr.io/cloudsql-docker/gce-proxy:latest
        command: ["/cloud_sql_proxy",
                  "-instances=GOOGLE_PROJECT:CLOUDSQL_ZONE:CLOUDSQL_INSTANCE=tcp:0.0.0.0:5432",
                  "-credential_file=/secrets/cloudsql/credentials.json"]
        ports:
        - containerPort: 5432
        volumeMounts:
        - name: cloudsql-instance-credentials
          mountPath: /secrets/cloudsql
          readOnly: true
      volumes:
      - name: cloudsql-instance-credentials
        secret:
          secretName: cloud-sql-instance-credentials

---
apiVersion: v1
kind: Service
metadata:
  name: cloudsql-proxy
  labels:
    app: cloudsql-proxy
spec:
  type: ClusterIP
  ports:
  - port: 5432
    targetPort: 5432
  selector:
    app: cloudsql-proxy
﻿
3. Create the cloud SQL auth proxy deployment in the namespace where the chart will be installed:
Shell
kubectl -n uns apply -f cloudsql-proxy.yaml
kubectl -n uns apply -f cloudsql-proxy.yaml
﻿
4. Deploy the chart with the following parameters:
YAML
postgres:
  enabled: false
  external:
    enabled: true
    host: "cloudsql-proxy"
    port: 5432
    secretName: ext-db-creds
postgres:
  enabled: false
  external:
    enabled: true
    host: "cloudsql-proxy"
    port: 5432
    secretName: ext-db-creds
﻿
Step 3: Upgrade Litmus UNS
Before upgrading from single mode to cluster mode (parameter mqtt.replicaCount > 1), and vice versa, scale down the MQTT StatefulSet to zero:
Shell
kubectl -n uns scale statefulset mqtt --replicas=0
kubectl -n uns scale statefulset mqtt --replicas=0
﻿
Step 4: Uninstall Litmus UNS
To uninstall the Helm chart with the release name uns in the namespace uns:
Shell
helm uninstall uns --namespace uns
helm uninstall uns --namespace uns
﻿
Ensure that you manually delete the Persistent Volume Claims (PVCs) for StatefulSets in Kubernetes, as they are not automatically removed.
Shell
PVCs=$(kubectl get pvc -o jsonpath='{.items[*].metadata.name}' -l app=uns -n uns)

for pvc in $PVCs; do
  kubectl delete pvc $pvc -n uns
done
PVCs=$(kubectl get pvc -o jsonpath='{.items[*].metadata.name}' -l app=uns -n uns)

for pvc in $PVCs; do
  kubectl delete pvc $pvc -n uns
done
﻿
FAQs
There are three possible solutions to solve this error.
1. Check if the Pull Secret is empty. Run the following command to verify:
Shell
kubectl describe serviceaccount uns-litmus-uns -n uns
kubectl describe serviceaccount uns-litmus-uns -n uns
﻿
2. Apply the Pull Secret if it's missing. Use this command to patch the service account:
Shell
kubectl patch serviceaccount uns-litmus-uns -p '{"imagePullSecrets": [{"name": "THE-SECRET-NAME"}]}' --namespace unss
kubectl patch serviceaccount uns-litmus-uns -p '{"imagePullSecrets": [{"name": "THE-SECRET-NAME"}]}' --namespace unss
﻿
3. Upgrade the Litmus UNS instance. Execute the following command to perform the upgrade:
Shell
helm upgrade uns oci://quay.io/litmusautomation/charts/litmus-uns --wait --namespace uns --create-namespace --set "imagePullSecrets[0].name=litmusautomation-uns-centralportal-pull-secret"
helm upgrade uns oci://quay.io/litmusautomation/charts/litmus-uns --wait --namespace uns --create-namespace --set "imagePullSecrets[0].name=litmusautomation-uns-centralportal-pull-secret"
﻿
﻿
Updated 26 Aug 2024
Define Access Control Lists (Rules and Permissions)
Access Broker and Client Statistics