Skip to content

Generic

This is a generic guide that demonstrates how to deploy Immuta into any Kubernetes cluster without dependencies on any particular cloud provider.

Considerations

For the purposes of this guide, the following state stores are deployed in Kubernetes using third-party Helm charts maintained by Bitnami:

Warning

Running production-grade stateful workloads (e.g, databases) in Kubernetes is difficult and heavily discouraged due to the following reasons.

  • Operational overhead: Managing PostgreSQL and ElasticSearch on Kubernetes requires expertise in deploying, maintaining, and scaling these databases and search engines effectively. This involves tasks like setting up monitoring, configuring backups, managing updates, and ensuring high availability. Cloud-managed services abstract much of this operational burden away, allowing teams to focus on application development rather than infrastructure management.
  • Resource allocation and scaling: Kubernetes requires careful resource allocation and scaling decisions to ensure that PostgreSQL and ElasticSearch have sufficient CPU, memory, and storage. Properly sizing these resources can be challenging and may require continuous adjustments as workload patterns change. Managed services typically handle this scaling transparently and can automatically adjust based on demand.
  • Data integrity and high availability: PostgreSQL and ElasticSearch deployments need robust strategies for data integrity and high availability. Kubernetes can facilitate high availability through pod replicas and distributed deployments, but ensuring data consistency and durability across database instances and search indexes requires careful consideration and often additional tooling.
  • Performance: Kubernetes networking and storage configurations can introduce performance overhead compared to native cloud services. For latency-sensitive applications or high-throughput workloads, these factors become critical in maintaining optimal performance.
  • Observability: Troubleshooting issues in a Kubernetes environment, especially related to database and search engine performance, can be complex. Managed services typically come with built-in monitoring, logging, and alerting capabilities tailored to the specific service, making it easier to identify and resolve issues.
  • Security and compliance: Kubernetes environments require careful attention to security best practices, including network policies, access controls, and encryption. Managed services often come pre-configured with security features and compliance certifications, reducing the burden on teams to implement and maintain these measures.

Pull the Immuta Enterprise Helm chart

  1. Navigate to the Immuta releases page to obtain the Kubernetes Helm Installation Credentials to authenticate with Immuta's Helm registry.

  2. Copy the snippet below and replace the placeholder text with the credentials you obtained in the previous step to add the Helm repository:

    echo <token> | helm repo add --username <username> --password-stdin immuta https://archives.immuta.com/charts

    --pass-credentials flag

    If you encounter an unauthorized error when adding the Immuta Enterprise Helm chart (IEHC), run helm repo add --pass-credentials.

    Usernames and passwords are only passed to the URL location of the Helm repository by default. The username and password are scoped to the scheme, host, and port of the Helm repository. To pass the username and password to other domains Helm may encounter when it goes to retrieve a chart, the new --pass-credentials flag can be used. This flag restores the old behavior for a single repository as an opt-in behavior.

    If you use a username and password for a Helm repository, you can audit the Helm repository in order to check for another domain that could have received the credentials. In the index.yaml file for that repository, look for another domain in the URL's list for the chart versions. If there is another domain found and that chart version is pulled or installed, the credentials will be passed on.

  3. Run the commands below to pull the latest Immuta Enterprise Helm chart or a specific version of the Immuta Enterprise Helm chart:

    • Latest chart:

      helm pull immuta/immuta-enterprise

    • Specific version:

      helm pull immuta/immuta-enterprise --version 2024.2.2

Setup

  1. Create a Kubernetes namespace named immuta for Immuta and its third-party dependencies.

    kubectl create namespace immuta

  2. Switch to namespace immuta.

    kubectl config set-context --current --namespace=immuta

  3. Create a container registry pull secret.

    Registry credentials

    Navigate to download.immuta.com to obtain credentials used to authenticate with Immuta's container registry.

    kubectl create secret docker-registry immuta-registry \
    --docker-server=https://registry.immuta.com \
    --docker-username="<username>" \
    --docker-password="<token>" \
    --email=support@immuta.com

ElasticSearch

  1. Create a Helm values file named es-values.yaml with the following content:

    es-values.yaml
    master:
    masterOnly: false
    replicaCount: 1

data:
    replicaCount: 0

coordinating:
    replicaCount: 0

ingest:
    replicaCount: 0

  2. Deploy ElasticSearch.

    helm install es-db oci://registry-1.docker.io/bitnamicharts/elasticsearch \
    --values es-values.yaml

PostgreSQL

  1. Create a Helm values file named pg-values.yaml with the following content:

    pg-values.yaml
    auth:
    database: immuta
    username: immuta
    password: <postgres-password>

  2. Update all placeholder values in the pg-values.yaml file.

  3. Deploy PostgreSQL.

    helm install pg-db oci://registry-1.docker.io/bitnamicharts/postgresql \
    --values pg-values.yaml

  4. Wait for all pods in the namespace to become ready.

    kubectl wait --for=condition=Ready pods --all

  5. Determine the name of the PostgreSQL database pod. This will be referenced in a subsequent step.

    kubectl get pod --selector "app.kubernetes.io/name=postgresql" --output template='{{ .metadata.name }}'

  6. Exec into the PostgreSQL database pod using the psql command and immuta user to configure the PostgreSQL user used by Immuta.

    kubectl exec --stdin --tty pod/<database-pod-name> -- psql -U immuta

  7. Alter the search_path for the immuta user.

    ALTER ROLE immuta SET search_path TO bometadata,public;

  8. Enable the pgcrypto extension.

    CREATE EXTENSION pgcrypto;

  9. Type \q then press Enter to exit.

Install Immuta

This section demonstrates how to deploy Immuta using the Immuta Enterprise Helm chart once the prerequisite local services are configured.

  1. Create a Helm values file named immuta-values.yaml with the following content:

    immuta-values.yaml
    global:
  imageRegistry: registry.immuta.com
  imagePullSecrets:
    - name: immuta-registry

audit:
  config:
    # Each Kubernetes Service has a DNS record associated with it. See: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
    # The anatomy of a domain name is as follows:
    #   <service>.<namespace>.svc.<cluster-domain>
    #
    # Where the default cluster domain is: cluster.local
    databaseConnectionString: postgres://immuta:<postgres-password>@pg-db-postgresql.immuta.svc.cluster.local:5432/immuta?schema=audit
    elasticsearchEndpoint: http://es-db-elasticsearch.immuta.svc.cluster.local:9200
    elasticsearchUsername: <elasticsearch-username>
    elasticsearchPassword: <elasticsearch-password>

secure:
  ingress:
    enabled: false
  extraEnvVars:
    - name: FeatureFlag_AuditService
      value: "true"
    - name: FeatureFlag_detect
      value: "true"
    - name: FeatureFlag_auditLegacyViewHide
      value: "true"

  postgresql:
    # Each Kubernetes Service has a DNS record associated with it. See: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
    # The anatomy of a domain name is as follows:
    #   <service>.<namespace>.svc.<cluster-domain>
    #
    # Where the default cluster domain is: cluster.local
    host: pg-db-postgresql.immuta.svc.cluster.local
    port: 5432
    database: immuta
    username: immuta
    password: <postgres-password>

  2. Update all placeholder values in the immuta-values.yaml file.

  3. Deploy Immuta.

    helm install immuta immuta/immuta-enterprise \
    --values immuta-values.yaml

Validation

  1. Wait for all pods in the namespace to become ready.

    kubectl wait --for=condition=Ready pods --all

  2. Determine the name of the Secure service.

    kubectl get service --selector "app.kubernetes.io/component=secure" --output template='{{ .metadata.name }}'

  3. Listen on local port 8080, forwarding TCP traffic to the Secure service's port named http.

    kubectl port-forward service/<name> 8080:http

  4. Navigate to http://localhost:8080 in a web browser.

Next steps