K3s Deployment

This is a generic guide that demonstrates how to deploy Immuta into K3s without dependencies on any particular cloud provider. Advanced Kubernetes expertise is required; therefore, it is not suitable for beginners.

Considerations

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

• PostgreSQL

• Elasticsearch

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.

Prerequisites

Checklist

This checklist outlines the necessary prerequisites for successfully deploying Immuta.

Credentials

• You have the credentials needed to access the ocir.immuta.com OCI registry. These can be viewed in your user profile at support.immuta.com.

Setup

Helm

Authenticate with OCI registry

echo <token> | helm registry login --password-stdin --username <username> ocir.immuta.com

Kubernetes

Creating a dedicated namespace ensures a logically isolated environment for your Immuta deployment, preventing resource conflicts with other applications.

Create namespace

1. Create a Kubernetes namespace named immuta.

   kubectl create namespace immuta

2. Switch to namespace immuta. All subsequent kubectl commands will default to this namespace.

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

Create registry secret

Create a container registry pull secret. Your credentials to authenticate with ocir.immuta.com can be viewed in your user profile at support.immuta.com.

kubectl create secret docker-registry immuta-oci-registry \
    --docker-server=https://ocir.immuta.com \
    --docker-username="<username>" \
    --docker-password="<token>" \
    --docker-email=[e-mail]

Elasticsearch

Install Helm chart

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

1. Deploy Elasticsearch.

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

2. Wait for all Elasticsearch pods to become ready.

   kubectl wait --for=condition=Ready pods --selector "app.kubernetes.io/name=elasticsearch"

PostgreSQL

Install Helm chart

1. Create a Helm values file named pg-values.yaml.

pg-values.yaml

primary:
  # The default 'nano' preset is insufficient and will lead to Out Of Memory (OOM) 
  # errors.
  #
  # Possible values: nano, micro, small, medium, large, xlarge, 2xlarge
  resourcesPreset: medium
  initdb:
    scripts:
      00_setup.sql: |
        CREATE ROLE immuta with LOGIN ENCRYPTED PASSWORD '<postgres-password>';
        ALTER ROLE immuta SET search_path TO bometadata,public;

        CREATE DATABASE temporal WITH OWNER immuta;
        CREATE DATABASE temporal_visibility WITH OWNER immuta;
        CREATE DATABASE immuta WITH OWNER immuta;

        GRANT ALL ON DATABASE temporal TO immuta;
        GRANT ALL ON DATABASE temporal_visibility TO immuta;
        GRANT ALL ON DATABASE immuta TO immuta;

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

2. Deploy PostgreSQL.

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

3. Wait for all PostgreSQL pods to become ready.

   kubectl wait --for=condition=Ready pods --selector "app.kubernetes.io/name=postgresql"

Configure databases

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

2. Exec into the PostgreSQL database pod using psql.

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

3. Configure the immuta database.

   \c immuta
   CREATE EXTENSION pgcrypto;

4. Configure the temporal database.

   \c temporal
   GRANT CREATE ON SCHEMA public TO immuta;

5. Configure the temporal_visibility database.

   \c temporal_visibility
   GRANT CREATE ON SCHEMA public TO immuta;
   CREATE EXTENSION btree_gin;

6. Exit the interactive prompt. Type \q, then press Enter.

Install Immuta

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

immuta-values.yaml

global:
  imageRegistry: ocir.immuta.com
  imagePullSecrets:
    - name: immuta-oci-registry
  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
    username: immuta
    password: <postgres-password>

audit:
  config:
    elasticsearchEndpoint: http://es-db-elasticsearch.immuta.svc.cluster.local:9200
    elasticsearchUsername: <elasticsearch-username>
    elasticsearchPassword: <elasticsearch-password>
  postgresql:
    database: immuta

secure:
  postgresql:
    database: immuta
  :
    hostname: <your-hostname>
    annotations:
      traefik.ingress.kubernetes.io/router.tls: "true"
    tls: true
    # If left unset the TLS secret name defaults to <hostname>-tls
    secretName: <secret-name>
    
temporal:
  enabled: true
  schema:
    createDatabase:
      enabled: false
  server:
    config:
      persistence:
        default:
          sql:
            database: temporal
        visibility:
          sql:
            database: temporal_visibility

1. Create a file named immuta-values.yaml with the above content, making sure to update all placeholder values.

2. Deploy Immuta.

   helm install immuta oci://ocir.immuta.com/stable/immuta-enterprise \
       --values immuta-values.yaml \
       --version 2024.3.9

3. Wait for all pods to become ready.

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

Validation

This section helps you validate your Immuta installation by temporarily accessing the application locally. However, this access is limited to your own computer. To enable access for other devices, you must configure Ingress.

1. Determine the name of the Secure service.

   kubectl get service --selector "app.kubernetes.io/component=secure" --output name

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

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

3. In a web browser, navigate to localhost:8080, to ensure the Immuta application loads.
4. Press Control+C to stop port forwarding.

Next step

Configure TLS certificates for K3s.