---
title: Deploying Litmus Unify on Kubernetes using Helm Chart
slug: unify/deploying-litmus-unify-on-kubernetes-using-helm-chart
docTags: 
createdAt: 2024-06-07T16:53:27.646Z
---

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](https://helm.sh/) 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.

```shell
sudo kubectl proxy --port=8080
```

:::hint{type="warning"}
**Note: **Download the LitmusUnify K8s Secret pull file from [Litmus Central Portal](https://portal.litmus.io/downloads?products=Litmus+Unify).
:::

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

```shell
sudo kubectl create namespace uns 
```

Set secret key name in Kubernetes resource with `uns` namespace.

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

Perform **helm **installation of the Unify chart.

```shell
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*.

:::hint{type="success"}
**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](https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-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](https://learn.microsoft.com/en-us/azure/aks/static-ip)**. 

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
```

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]--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:

```shell
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:

```yaml
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

:::hint{type="info"}
**Note:** Follow the [Google Cloud SQL documentation](https://cloud.google.com/sql/docs/postgres) to deploy an instance of Cloud SQL for PostgreSQL.
:::

In this example, we will use the [Cloud SQL Auth Proxy](https://cloud.google.com/sql/docs/postgres/connect-kubernetes-engine#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
```

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
```

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
```

4\. Deploy the chart with the following parameters:

```yaml
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:

```shell
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`:

```shell
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
```

# FAQs

:::ExpandableHeading{isOpen="true"}
What should I do if I encounter the error `INSTALLATION FAILED: context deadline exceeded` during Unify installation? 

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
```

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 uns
```

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

```shell
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"
```
:::