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