2025.2 RC installation on AWS

Immuta Manual Installation Guide (2025.2.X)

This guide provides step-by-step instructions for manually deploying Immuta 2025.2.X to a Kubernetes cluster

Prerequisites

• AWS CLI configured with appropriate IAM permissions for EKS, RDS, and IAM operations

• kubectl installed and configured

• Helm 3 installed

• Standard Unix utilities: envsubst, uuidgen, curl

• Access to the target Kubernetes cluster

• Required secrets and credentials (see Variables section)

• immutactl binary (download link to be provided by Immuta support)

Required Variables

Before starting, set these environment variables or note them for use in commands:

# Required inputs
export NAMESPACE="your-namespace"              # e.g., lf-rc-12345 (dash-case)
export DB_PREFIX="your_db_prefix"             # e.g., lf_rc_12345 (snake_case)
export CHART_VERSION="2025.2.0-rc.2"         # Immuta Helm chart version
export CHART_CHANNEL="unstable"              # stable or unstable
export FLOW_RELAY_BUCKET="your-unique-bucket-name" # S3 bucket for Flow Relay (must be globally unique)

# AWS Configuration
export AWS_ACCOUNT_ID="931788537711"
export AWS_REGION="us-east-1"
export CLUSTER_NAME="cs-support-env"
export RDS_HOST="immuta-support.ci6mpw1cd1j3.us-east-1.rds.amazonaws.com"
export OIDC_PROVIDER="oidc.eks.us-east-1.amazonaws.com/id/188A72A9F52282D01124D4A86BB09289"
export IMMUTA_DOMAIN="your-domain.com"              # Replace with your actual domain

# Derived variables
export DB_PREFIX_DASH="$NAMESPACE"

# Required secrets (replace with actual values)
export IMMUTA_REGISTRY_USERNAME="your-registry-username"
export IMMUTA_REGISTRY_PASSWORD="your-registry-password"
export POSTGRES_ADMIN_PASSWORD="your-postgres-admin-password"
export IMMUTA_DB_PASSWORD="your-immuta-db-password"

Required Files

The following files need to be created locally before beginning the installation. Copy each file content to the specified path:

1. IAM Policy Templates

templates/trust-policy-template.json

{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Federated": "arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/${OIDC_PROVIDER}"
        },
        "Action": "sts:AssumeRoleWithWebIdentity",
        "Condition": {
          "StringLike": {
            "${OIDC_PROVIDER}:sub": "system:serviceaccount:${NAMESPACE}:immuta-*"
          },
          "StringEquals": {
            "${OIDC_PROVIDER}:aud": "sts.amazonaws.com"
          }
        }
      }
    ]
  }

templates/s3-access-policy-template.json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:AbortMultipartUpload",
        "s3:GetBucketLocation",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:ListAllMyBuckets",
        "s3:ListMultipartUploadParts",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::${FLOW_RELAY_BUCKET}",
        "arn:aws:s3:::${FLOW_RELAY_BUCKET}/*"
      ]
    }
  ]
}

templates/lakeformation-policy-template.json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "glue:GetDatabase",
        "glue:GetTables",
        "glue:GetDatabases",
        "glue:GetTable",
        "lakeformation:ListPermissions",
        "lakeformation:BatchGrantPermissions",
        "lakeformation:BatchRevokePermissions",
        "lakeformation:CreateLFTag",
        "lakeformation:UpdateLFTag",
        "lakeformation:DeleteLFTag",
        "lakeformation:AddLFTagsToResource",
        "lakeformation:RemoveLFTagsFromResource",
        "lakeformation:GetResourceLFTags",
        "lakeformation:ListLFTags",
        "lakeformation:GetLFTag",
        "lakeformation:SearchTablesByLFTags",
        "lakeformation:SearchDatabasesByLFTags"
      ],
      "Resource": "*"
    }
  ]
}

2. Helm Values Files

es-values.yaml

master:
    masterOnly: false
    replicaCount: 1

data:
    replicaCount: 0

coordinating:
    replicaCount: 0

ingest:
    replicaCount: 0

immuta-values.yaml

global:
  imageRegistry: ocir.immuta.com
  imagePullSecrets:
    - name: immuta-oci-registry
  featureFlags:
    dsia: true
    dsiaDatabricksUnityCatalog: true
    dsiaFrontend: true
    dsiaFrontendRegistrationSettings: true
    dsiaGlue: true
    nativeS3Integration: true
    policyWorkflowServiceSync: true
  tenantId: "${TENANT_ID}"
  postgresql:
    host: "${RDS_HOST}"
    port: 5432
    username: "${DB_PREFIX_UNDERSCORE}"
    password: "${IMMUTA_DB_PASSWORD}"
  flowRelay:
    store: s3
    storeRegion: "${AWS_REGION}"
    storeBucket: "${FLOW_RELAY_BUCKET}"
    storePrefix: "${DB_PREFIX_DASH}"

audit:
  config:
    elasticsearchEndpoint: http://es-db-elasticsearch.${NAMESPACE}.svc.cluster.local:9200
  postgresql:
    database: "${DB_PREFIX_UNDERSCORE}_immuta"

secure:
  serviceAccount:
    create: true
    name: immuta-secure
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::${AWS_ACCOUNT_ID}:role/${DB_PREFIX_DASH}-immuta-irsa
  postgresql:
    ssl: true
    database: "${DB_PREFIX_UNDERSCORE}_immuta"
  extraConfig:
    publicImmutaUrl: "https://${IMMUTA_DOMAIN}"
    schedule:
      policyWorkflowServiceSync: '*/1 * * * *'
  extraEnvVars:
    - name: NODE_DEBUG
      value: http

gateway:
  ingress:
    enabled: true
    hostname: "${IMMUTA_DOMAIN}"
    annotations:
      alb.ingress.kubernetes.io/backend-protocol: HTTP
      alb.ingress.kubernetes.io/group.name: immuta-support
      alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS":443}]'
      alb.ingress.kubernetes.io/scheme: internet-facing
      alb.ingress.kubernetes.io/ssl-redirect: "443"
      alb.ingress.kubernetes.io/target-type: ip
    ingressClassName: alb
    tls: true

temporal:
  enabled: true
  server:
    extraVolumes:
      - name: secret-with-certs
        secret:
          secretName: secret-with-certs
    extraVolumeMounts:
      - name: secret-with-certs
        mountPath: /certs/
    config:
      persistence:
        default:
          sql:
            database: "${DB_PREFIX_UNDERSCORE}_temporal"
            tls:
              caFile: /certs/global-bundle.pem
              enabled: true
        visibility:
          sql:
            database: "${DB_PREFIX_UNDERSCORE}_temporal_visibility"
            tls:
              caFile: /certs/global-bundle.pem
              enabled: true

now:
  postgresql:
    database: "${DB_PREFIX_UNDERSCORE}_immuta"
    params:
      schema: now
      sslmode: no-verify
  serviceAccount:
    name: immuta-now
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::${AWS_ACCOUNT_ID}:role/${DB_PREFIX_DASH}-immuta-irsa

policy:
  serviceAccount:
    name: immuta-policy
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::${AWS_ACCOUNT_ID}:role/${DB_PREFIX_DASH}-immuta-irsa

3. Setup Script

Create the required directory structure and files:

# Create directory structure
mkdir -p templates

# Copy each file content above into the respective paths
# For example:
# cat > templates/trust-policy-template.json << 'EOF'
# [paste content here]
# EOF

Note: The envsubst and uuidgen commands are used in the installation steps. Ensure these utilities are available on your system.

Step 1: Setup immutactl

Download and install the immutactl binary:

# Download immutactl binary (replace with actual download URL provided by Immuta support)
# curl -LO https://your-download-url/immutactl-linux

# Install immutactl
sudo mv ./immutactl-linux /usr/local/bin/immutactl
sudo chmod +x /usr/local/bin/immutactl

# Verify installation
immutactl

Note: Contact Immuta support for the correct download URL for the immutactl binary.

Step 2: Create S3 Bucket

Create the S3 bucket for Flow Relay storage:

# Create the S3 bucket
aws s3 mb s3://${FLOW_RELAY_BUCKET} --region ${AWS_REGION}

# Verify bucket creation
aws s3 ls s3://${FLOW_RELAY_BUCKET}

Note: S3 bucket names must be globally unique. If the bucket creation fails, choose a different name for FLOW_RELAY_BUCKET.

Step 3: Create IAM Roles and Policies

Create the necessary IAM role and policies for IRSA:

ROLE_NAME="${DB_PREFIX_DASH}-immuta-irsa"
S3_POLICY_NAME="${ROLE_NAME}-policy"
TRUST_POLICY_FILE="trust-policy.json"
IAM_POLICY_FILE="s3-access-policy.json"
LAKEFORMATION_POLICY_FILE="lakeformation-policy.json"

# Render trust policy from template using envsubst
envsubst < templates/trust-policy-template.json > $TRUST_POLICY_FILE
echo "----- trust-policy.json -----"
cat $TRUST_POLICY_FILE

# Render IAM policy for flowRelay from template using envsubst
envsubst < templates/s3-access-policy-template.json > $IAM_POLICY_FILE
echo "----- s3-access-policy.json -----"
cat $IAM_POLICY_FILE

# Render Lake Formation policy from template using envsubst
envsubst < templates/lakeformation-policy-template.json > $LAKEFORMATION_POLICY_FILE
echo "----- lakeformation-policy.json -----"
cat $LAKEFORMATION_POLICY_FILE

# Create the IAM policy
S3_POLICY_ARN=$(aws iam create-policy --policy-name "$S3_POLICY_NAME" --policy-document file://$IAM_POLICY_FILE --query 'Policy.Arn' --output text)

# Create the Lake Formation policy
LAKEFORMATION_POLICY_ARN=$(aws iam create-policy --policy-name "${ROLE_NAME}-lakeformation-policy" --policy-document file://$LAKEFORMATION_POLICY_FILE --query 'Policy.Arn' --output text)

# Create the IAM role
aws iam create-role --role-name "$ROLE_NAME" --assume-role-policy-document file://$TRUST_POLICY_FILE

# Attach the policies to the role
aws iam attach-role-policy --role-name "$ROLE_NAME" --policy-arn "$S3_POLICY_ARN"
aws iam attach-role-policy --role-name "$ROLE_NAME" --policy-arn "$LAKEFORMATION_POLICY_ARN"

Step 3: Create IAM Roles and Policies

Create the necessary IAM role and policies for IRSA:

ROLE_NAME="${DB_PREFIX_DASH}-immuta-irsa"
S3_POLICY_NAME="${ROLE_NAME}-policy"
TRUST_POLICY_FILE="trust-policy.json"
IAM_POLICY_FILE="s3-access-policy.json"
LAKEFORMATION_POLICY_FILE="lakeformation-policy.json"

# Render trust policy from template using envsubst
envsubst < templates/trust-policy-template.json > $TRUST_POLICY_FILE
echo "----- trust-policy.json -----"
cat $TRUST_POLICY_FILE

# Render IAM policy for flowRelay from template using envsubst
envsubst < templates/s3-access-policy-template.json > $IAM_POLICY_FILE
echo "----- s3-access-policy.json -----"
cat $IAM_POLICY_FILE

# Render Lake Formation policy from template using envsubst
envsubst < templates/lakeformation-policy-template.json > $LAKEFORMATION_POLICY_FILE
echo "----- lakeformation-policy.json -----"
cat $LAKEFORMATION_POLICY_FILE

# Create the IAM policy
S3_POLICY_ARN=$(aws iam create-policy --policy-name "$S3_POLICY_NAME" --policy-document file://$IAM_POLICY_FILE --query 'Policy.Arn' --output text)

# Create the Lake Formation policy
LAKEFORMATION_POLICY_ARN=$(aws iam create-policy --policy-name "${ROLE_NAME}-lakeformation-policy" --policy-document file://$LAKEFORMATION_POLICY_FILE --query 'Policy.Arn' --output text)

# Create the IAM role
aws iam create-role --role-name "$ROLE_NAME" --assume-role-policy-document file://$TRUST_POLICY_FILE

# Attach the policies to the role
aws iam attach-role-policy --role-name "$ROLE_NAME" --policy-arn "$S3_POLICY_ARN"
aws iam attach-role-policy --role-name "$ROLE_NAME" --policy-arn "$LAKEFORMATION_POLICY_ARN"

Step 4: Configure Kubernetes Access

Update your kubeconfig to access the target cluster:

aws eks --region $AWS_REGION update-kubeconfig --name $CLUSTER_NAME

Step 5: Create and Configure Namespace

Create the Kubernetes namespace and apply labels:

# Create namespace
kubectl create namespace $NAMESPACE

# Label namespace
kubectl label namespace $NAMESPACE purpose=upgrade-test owner=manual-deployment --overwrite

Step 6: Create Registry Pull Secret

Create the Docker registry secret for pulling Immuta images:

kubectl create secret -n $NAMESPACE docker-registry immuta-oci-registry \
  --docker-server=https://ocir.immuta.com \
  --docker-username=$IMMUTA_REGISTRY_USERNAME \
  --docker-password=$IMMUTA_REGISTRY_PASSWORD \
  [email protected]

Step 7: Deploy Elasticsearch

Deploy Elasticsearch using Helm:

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

Step 8: Create PostgreSQL Databases

Create the required PostgreSQL databases using immutactl:

immutactl postgres --host "$RDS_HOST" \
                   --prefix $DB_PREFIX \
                   --immuta-role $DB_PREFIX \
                   --admin-role rds_superuser \
                   --admin-password "$POSTGRES_ADMIN_PASSWORD" \
                   --immuta-password $IMMUTA_DB_PASSWORD

Step 9: Prepare Helm Values

Prepare the Helm values file and generate required values:

# Generate tenantId
export TENANT_ID=$(uuidgen)

# Render final Helm values
export DB_PREFIX_UNDERSCORE="${DB_PREFIX}"
export DB_PREFIX_DASH="${DB_PREFIX_DASH}"
export IMMUTA_DB_PASSWORD="${IMMUTA_DB_PASSWORD}"
export RDS_HOST="${RDS_HOST}"
export NAMESPACE="${NAMESPACE}"
export TENANT_ID="${TENANT_ID}"
export IMMUTA_DOMAIN="${IMMUTA_DOMAIN}"

envsubst < immuta-values.yaml > rendered-immuta-values.yaml

Step 10: Review Rendered Values

Review the rendered Helm values before deployment:

echo "=== Rendered Immuta Values ==="
cat rendered-immuta-values.yaml

Step 11: Add RDS Certificate Bundle

Add the RDS global certificate bundle as a Kubernetes secret:

# Download the RDS global bundle
curl -o global-bundle.pem https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

# Create the secret
kubectl -n "$NAMESPACE" create secret generic secret-with-certs \
  --from-file=global-bundle.pem \
  --dry-run=client -o yaml | kubectl apply -f -

Step 12: Deploy Immuta

Deploy Immuta using Helm:

# Login to Immuta registry
helm registry login ocir.immuta.com \
  --username "$IMMUTA_REGISTRY_USERNAME" \
  --password "$IMMUTA_REGISTRY_PASSWORD"

# Deploy Immuta
helm upgrade --install immuta oci://ocir.immuta.com/${CHART_CHANNEL}/immuta-enterprise \
  -n "$NAMESPACE" \
  --version $CHART_VERSION \
  -f rendered-immuta-values.yaml

Step 13: Wait for Deployment Completion

Wait for all Immuta deployments to become ready:

for deploy in $(kubectl get deploy -n "$NAMESPACE" -o jsonpath='{.items[*].metadata.name}' | tr ' ' '\n' | grep '^immuta-'); do
  echo "Waiting for deployment $deploy to be ready..."
  kubectl rollout status deployment/$deploy -n "$NAMESPACE" --timeout=300s || true
done

Verification

After deployment completes, verify the installation:

# Check all pods are running
kubectl get pods -n $NAMESPACE

# Check ingress is created
kubectl get ingress -n $NAMESPACE

# Get the ALB DNS name for your domain configuration
kubectl get ingress -n $NAMESPACE -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}'

Note: You'll need to configure your DNS to point ${IMMUTA_DOMAIN} to the ALB hostname before accessing the Immuta UI.

Troubleshooting

DNS Configuration

Since this manual installation doesn't include the automated DNS setup, you'll need to:

1. Configure your domain's DNS to point ${IMMUTA_DOMAIN} to your ALB

2. Get the ALB DNS name using: kubectl get ingress -n $NAMESPACE

3. Create a CNAME record pointing your domain to the ALB DNS name

Common Issues

1. Pod Not Starting: Check pod logs using kubectl logs -n $NAMESPACE <pod-name>

2. ImagePullBackOff: Verify registry credentials and secret creation

3. Database Connection Issues: Confirm RDS host accessibility and credentials

4. Helm Deployment Failures: Check Helm values rendering and template syntax

Useful Commands

# Check pod status
kubectl get pods -n $NAMESPACE

# View pod logs
kubectl logs -n $NAMESPACE <pod-name>

# Check services
kubectl get svc -n $NAMESPACE

# Check ingress
kubectl get ingress -n $NAMESPACE

# Describe a resource for more details
kubectl describe <resource-type> <resource-name> -n $NAMESPACE

Cleanup

To remove the deployment:

# Uninstall Helm releases
helm uninstall immuta -n $NAMESPACE
helm uninstall es-db -n $NAMESPACE

# Delete namespace
kubectl delete namespace $NAMESPACE

# Clean up IAM resources
aws iam detach-role-policy --role-name "${DB_PREFIX_DASH}-immuta-irsa" --policy-arn "$S3_POLICY_ARN"
aws iam detach-role-policy --role-name "${DB_PREFIX_DASH}-immuta-irsa" --policy-arn "$LAKEFORMATION_POLICY_ARN"
aws iam delete-role --role-name "${DB_PREFIX_DASH}-immuta-irsa"
aws iam delete-policy --policy-arn "$S3_POLICY_ARN"
aws iam delete-policy --policy-arn "$LAKEFORMATION_POLICY_ARN"

# Clean up S3 bucket (WARNING: This will delete all data in the bucket)
aws s3 rm s3://${FLOW_RELAY_BUCKET} --recursive
aws s3 rb s3://${FLOW_RELAY_BUCKET}