Skip to content

You are viewing documentation for Immuta version 2.8.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

Kubernetes Helm Installation

Audience: System Administrators

Content Summary: This page outlines how to install Kubernetes Helm.

If using a Kubernetes namespace...

If deploying Immuta into a Kubernetes namespace other than the default, you must include the --namespace option into all helm and kubectl commands provided throughout this section.

Installation

In order to conduct an installation of Immuta in a Kubernetes environment, you will need Helm access to the Kubernetes cluster.

Step 1.) Environment Config

a.) Check Helm version

Immuta's Helm Chart requires Helm version 2.16+ or 3+.

  • Helm 2.16+ is only supported for existing Immuta installations.
  • New installations of Immuta must use the latest version of Helm 3 and Immuta's latest Chart.

Run helm version to verify the version of Helm you are using:

helm version
Example Output 
version.BuildInfo{Version:"v3.2.3", GitCommit:"8f832046e258e2cb800894579b1b3b50c2d83492", GitTreeState:"clean", GoVersion:"go1.13.12"}

Client: &version.Version{SemVer:"v2.16.1", GitCommit:"bbdfe5e7803a12bbdf97e94cd847859890cf4050", GitTreeState:"clean"}
Server: &version.Version{SemVer:"v2.16.1", GitCommit:"bbdfe5e7803a12bbdf97e94cd847859890cf4050", GitTreeState:"clean"}
If using Helm 2, ensure your Helm version matches Tiller in the cluster

Keeping your Helm version matched to your Tiller version is best practice and can avoid incompatibility issues. Run helm version to compare versions and ensure sync.

$ helm version
Client: &version.Version{SemVer:"v2.16.1", GitCommit:"bbdfe5e7803a12bbdf97e94cd847859890cf4050", GitTreeState:"clean"}
Server: &version.Version{SemVer:"v2.16.1", GitCommit:"bbdfe5e7803a12bbdf97e94cd847859890cf4050", GitTreeState:"clean"}

b.) Configure Immuta's Helm Chart repo

In order to deploy Immuta to your Kubernetes cluster, you must be able to access the Immuta Helm Chart Repository and the Immuta Docker Registry. You can obtain credentials and instructions to set up both of these by accessing the Immuta Release Portal.

Run helm repo list to ensure Immuta's Helm Chart repository has been successfully added:

helm repo list
Example Output 
NAME            URL
stable          https://kubernetes-charts.storage.googleapis.com
local           http://127.0.0.1:8879/charts
immuta          https://archives.immuta.com/charts
Don't forget the image pull secret!

As detailed in Immuta Release Portal, you must create a Kubernetes Image Pull Secret in the namespace that you are deploying Immuta in, or the Pods will fail to start due to ErrImagePull.

Run kubectl get secrets to confirm your Kubernetes image pull secret is in place:

kubectl get secrets
Example Output 
NAME                  TYPE                                  DATA   AGE
immuta-registry       kubernetes.io/dockerconfigjson        1      5s

c.) Check/Update your local Immuta Helm Chart version

Run helm search repo immuta to check the version of your local copy of Immuta's Helm Chart:

helm search repo immuta
Example Output 
NAME            CHART VERSION   APP VERSION   DESCRIPTION
immuta/immuta   4.5.0           2020.2.4      Immuta: Automated Data Governance

Update your local Chart by running helm repo update.

To perform an upgrade without upgrading to the latest version of the Chart, run helm list to determine the Chart version of the installed release, and then specify that version using the --version argument of helm repo update.

Step 2: Configure Immuta Helm Values

Once you have the Immuta Docker Registry and Helm Chart Repository configured, download the immuta-values.yaml file below. This values file is a recommended starting point for your installation.

Download immuta-values.yaml

Fill in and modify immuta-values.yaml based on the determined configuration for your Kubernetes cluster and the desired Immuta installation. Replace the placeholder password value "<GENERATE_PASSWORD>" with a secure password.

Avoid these special characters in generated passwords

whitespace, $, &, : , \, /, '

Step 3: Configuring Backup and Restoration Values

At this point this procedure forks depending on whether you are installing with the intent of restoring from a backup or not. Use the bullets below to determine which step to follow.

  • If this is a new install with no restoration needed, follow Step 3A.
  • If you are upgrading a previous installation using the full backup and restore (Procedure B), follow Step 3B.

Step 3A: Initial Immuta Kubernetes Installation -- No Backup Restoration

Immuta's current Helm Chart provides a built-in backup mechanism based on a PersistentVolumeClaim. In order for this feature to work, the Kubernetes cluster Immuta is being installed into must support PersistentVolumes with an access mode of ReadWriteMany. If such a resource is available, Immuta's Helm Chart will set everything up for you if you enable backups and comment out the volume and claimName.

backup:
  # set to true to enable backups. requires RWX persistent volume support
  enabled: true
  #volume:
    # if claimName is set to an existing PVC no PV/PVC will be created
    #claimName: <YOUR ReadWriteMany PersistentVolumeClaim NAME>
  restore:
    # set to true to enable restoring from backups. This should be enabled whenever backups are enabled
    enabled: false

If your Kubernetes cluster does not presently support PersistentVolumes with an access mode of ReadWriteMany, consult the subsections of this section of the documentation that are specific to your cloud provider for assistance in configuring a compatible resource. If your Kubernetes environment is not represented there, or a workable solution does not appear available, please contact your Immuta representative to discuss options.

Step 3B: Immuta Kubernetes Re-Installation -- Restore From Backup

If you are upgrading a previous installation using the full backup and restore procedure (Procedure B), a valid PersistentVolumeClaim containing your backup must be available. That claim simply needs to be configured in your immuta-values.yaml along with the restore option enabled so that during the install the databases will be fully restored.

backup:
  # set to true to enable backups. requires RWX persistent volume support
  enabled: true
  volume:
    # if claimName is set to an existing PVC no PV/PVC will be created
    claimName: <YOUR ReadWriteMany PersistentVolumeClaim NAME>
  restore:
    # set to true to enable restoring from backups. This should be enabled whenever backups are enabled
    enabled: true

If you are unsure of the value for <YOUR ReadWriteMany PersistentVolumeClaim NAME>, the command kubectl get pvc will list it for you

kubectl get pvc
Example Output 
NAME                 STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
test-immuta-backup   Bound    pvc-2ca50bff-8c2c-487c-b7bf-75c3764c470a   5Gi        RWX            standard       39h

Step 4: Deploy Immuta

helm install <YOUR RELEASE NAME> immuta/immuta \
  --values immuta-values.yaml

helm install immuta/immuta \
  --values immuta-values.yaml \
  --name <YOUR RELEASE NAME>
Troubleshooting

If you encounter errors while deploying the Immuta Helm Chart, see Troubleshooting.

Advanced Installations

Managing TLS

HTTP communication using TLS certificates is enabled by default in Immuta's Helm Chart for both internal (inside the Kubernetes cluster) and external (between the Kubernetes ingress and the outside world) communications. This is accomplished through the generation of a local certificate authority (CA) which signs certificates for each service - all handled automatically by the Immuta installation. While not recommended, if TLS must be disabled for some reason, this can be done by setting tls.enabled to false in the values file.

Using Your Own TLS Certificate(s)

It is possible to use your own TLS certificate for external (outside the Kubernetes cluster) communications. This is recommended for Immuta production deployments.

Using your own certificates requires you to create a Kubernetes Secret containing the private key, certificate, and certificate authority certificate. This can be easily done using kubectl:

kubectl create secret generic immuta-external-tls \
    --from-file=tls.crt=<path to your.pem cert> \
    --from-file=tls.key=<path to your-key.pem key> \
    --from-file=ca.crt=<path to your-ca.pem cert>
Make sure your certificates are correct

Make sure the certificate's Common Name (CN) and/or Subject Alternative Name (SAN) matches the specified externalHostname or contains an appropriate wildcard.

After creating the Kubernetes Secret, specify its use in the external ingress by setting tls.externalSecretName = immuta-external-tls in your values file.

Resource Limits

The Immuta helm chart supports Resource Limits for all components. The resource recommendations below are for a Kubernetes cluster running 3 worker nodes and 1 master, where the worker nodes are a m4.xlarge (4 vCPU, 16GB RAM) or equivalent:

web:
  resources:
    requests:
      memory: "512Mi"
    limits:
      memory: "2Gi"

database:
  resource:
    requests:
      memory: "512Mi"
    limits:
      memory: "2Gi"

queryEngine:
  resource:
    requests:
      memory: "512Mi"
    limits:
      memory: "4Gi"

fingerprint:
  resources:
    requests:
      memory: "512Mi"
    limits:
      memory: "2Gi"

memcached:
  maxItemMemory: 256
  resources:
    requests:
      memory: "256Mi"
    limits:
      memory: "256Mi"

Similarly, for an m4.large (2 vCPU, 8GB RAM) or equivalent:

web:
  resources:
    requests:
      memory: "256Mi"
    limits:
      memory: "1Gi"

database:
  resources:
    requests:
      memory: "512Mi"
    limits:
      memory: "2Gi"

queryEngine:
  resources:
    requests:
      memory: "512Mi"
    limits:
      memory: "2Gi"

fingerprint:
  resources:
    requests:
      memory: "256Mi"
    limits:
      memory: "1Gi"

memcached:
  maxItemMemory: 256
  resources:
    requests:
      memory: "256Mi"
    limits:
      memory: "256Mi"

Using Argo CD

The Immuta Helm Chart (version 4.5.0+) can be deployed using Argo CD.

Use these Helm values to ensure compatibility.

hooks:
  tlsGeneration:
    hookAnnotations:
      helm.sh/hook-delete-policy: "before-hook-creation"
tls:
  manageGeneratedSecret: true

The TLS generation hook must be run with a hook delete policy of "before-hook-creation" to ensure that job resources are not deleted before the job has completed.

tls.manageGeneratedSecret must be set to true when using Argo CD to deploy Immuta; otherwise, the generated TLS secret will be shown as OutOfSync (requires pruning) in Argo CD. Pruning the Secret would break TLS for the deployment, so it is important to set this value to prevent that from happening.

Troubleshooting

For detailed assistance in troubleshooting your installation, please contact your Immuta Support Professional.