Deploying Litmus Unify on Kubernetes using Helm Chart

18 min

You can deploy Litmus Unify on Kubernetes using a Helm chart. This chart initializes a Litmus Unify 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

Make sure kubectl proxy is started on a separate console window or in the background.

If a kubectl proxy is not used, the kubeconfig file will need to be adjusted to accommodate this.

sudo kubectl proxy --port=8080

Note: Download the LitmusUnify K8s Secret pull file from Litmus Central Portal.

Given that we have the secret yaml file in our current working directory.

sudo kubectl create namespace uns

Set secret key name in Kubernetes resource with uns namespace.

sudo kubectl create -f litmusautomation-uns-centralportal-secret.yml --namespace=uns

Perform helm installation of the Unify chart.

helm install uns oci://quay.io/litmusautomation/charts/litmus-uns --version=1.3.4 --wait --namespace uns --create-namespace --set "imagePullSecrets[0].name=litmusautomation-uns-centralportal-pull-secret"

The user can try to log in with https://ipaddress and username/password: admin/admin.

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 Unify using Helm.

Step 1: Configure SSL Certificates for Unify

The Helm chart can configure SSL/TLS for the Unify 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:

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:

helm upgrade -n [namespace] [release] [chart]--version=1.3.4 --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:

helm upgrade -n uns uns oci://quay.io/litmusautomation/charts/litmus-uns --version=1.3.4 --set luns.tlsSecretName=new-secret-name

Step 2: Using External Database for Unify

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:

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:

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:

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:

kubectl -n uns apply -f cloudsql-proxy.yaml

4. Deploy the chart with the following parameters:

postgres:
  enabled: false
  external:
    enabled: true
    host: "cloudsql-proxy"
    port: 5432
    secretName: ext-db-creds

Step 3: Upgrade Unify

Before upgrading from single mode to cluster mode (parameter mqtt.replicaCount > 1), and vice versa, scale down the MQTT StatefulSet to zero:

kubectl -n uns scale statefulset mqtt --replicas=0

Step 4: Uninstall Unify

To uninstall the Helm chart with the release name uns in the 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.

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:

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:

kubectl patch serviceaccount uns-litmus-uns -p '{"imagePullSecrets": [{"name": "THE-SECRET-NAME"}]}' --namespace uns

3. Upgrade the Unify instance. Execute the following command to perform the upgrade:

helm upgrade uns oci://quay.io/litmusautomation/charts/litmus-uns --version=1.3.4 --wait --namespace uns --create-namespace --set "imagePullSecrets[0].name=litmusautomation-uns-centralportal-pull-secret"