Content Inspection On-Premises Installation Guide

This guide covers the installation of the Content Inspection (CI) stack in customer-controlled managed Kubernetes environments.

Supported Platforms

• Google Cloud Platform: GKE cluster
• Amazon Web Services: EKS cluster
• Microsoft Azure: AKS cluster

Global Prerequisites

Infrastructure Requirements

• Kubernetes cluster with minimum node specifications:
  • 4 vCPUs per node
  • 16GB RAM per node
• Working Ingress controller installed and tested
• Valid TLS certificate for your ingress hostname
• Sufficient storage quota in your cloud provider for cache buckets

Required Tools

• helm (v3.x)
• kubectl configured for your cluster
• Cloud provider CLI tools:
  • GCP: gcloud
  • AWS: aws CLI and eksctl
  • Azure: az CLI

Install Token

Obtain your install token from the Cyberhaven dashboard installers page. The token must follow this format:

{"dlp_host": "https://your-environment.cyberhaven.io", "install_token": "your-actual-token-here"}

Only modify the install_token field value - keep the rest of the JSON structure unchanged.

Prerequisites Checklist

• Kubernetes cluster is ready and accessible
• Ingress controller is installed and tested
• TLS certificate is available for your domain
• Cloud storage permissions are configured
• Container image registry access is configured
• Install token obtained from Cyberhaven dashboard

Chart Access Configuration

The CI stack images are hosted in Cyberhaven's private registry. Access options:

Option 1: Pull Secret

Use the pull secret provided by Cyberhaven:

kubectl create secret docker-registry gcp-artifact-registry \
    --docker-server=us-docker.pkg.dev \
    --docker-username=_json_key \
    --docker-password="$(cat <ARTIFACT_READER_KEY>.json)" \
    --docker-email=support@cyberhaven.com

Test Registry Access

docker login us-docker.pkg.dev/cyberhaven-cd/external -u _json_key -p "$(cat <ARTIFACT_READER_KEY>.json)"

Option 2: Direct Service Account Access (GCP)

For GCP deployments, your service account can be granted direct registry access, eliminating the need for pull secrets.

Configuration Values

Configure values/customer-values.yaml for your environment:

Provider Configuration

global:
  customer:
    provider:
      type: "gcp"  # gcp, aws, or azure
      serviceAccount: "your-sa@project.iam.gserviceaccount.com"  # GCP only
      # clientId: "client-id"      # Azure only  
      # roleArn: "arn:aws:iam::"   # AWS only

Cache Storage

global:
  customer:
    cache:
      type: "gcs"        # gcs, s3, or azblob
      name: "cache-bucket-name"

Ingress Configuration

global:
  customer:
    ingress:
      enabled: true
      className: "nginx"  # or your ingress class
      annotations:
        nginx.ingress.kubernetes.io/proxy-body-size: "25m"
        nginx.ingress.kubernetes.io/proxy-read-timeout: "200"
      tls: []  # Configure TLS as needed

SaaS Integration

The SaaS configuration section will be provided by Cyberhaven before deployment. Copy this configuration to your values/customer-values.yaml:

global:
  customer:
    saas:
      googleCredentials: |
        {
          # Workload identity federation JSON (provided by Cyberhaven)
        }

Note: For GCP deployments, this section is not needed - only specify the serviceAccount above. For AWS/Azure deployments, Cyberhaven will provide the complete saas configuration.

Provider-Specific Setup

Complete the provider-specific setup before installation:

• GCP: GCP
• AWS: AWS
• Azure: Azure

Installation Procedure

1. Download Chart

VERSION=<CHART-VERSION-PROVIDED-BY-CYBERHAVEN>
helm pull oci://us-docker.pkg.dev/cyberhaven-cd/external/charts/ci-stack-onprem --untar --version $VERSION
cd ci-stack-onprem

2. Configure Values

Edit values/customer-values.yaml with your environment settings from the provider-specific procedure.

3. Dry-Run Validation (Required)

IMAGES_TAG=<your-tag> INSTALL_TOKEN='<your-install-token>' make template DRY_RUN=true

4. Deploy

Required variables:

IMAGES_TAG=v25.04.20-80c9a23d INSTALL_TOKEN='{"dlp_host":"https://example.cyberhaven.io","install_token":"your-token"}' make upgrade

Optional variables: NAMESPACE (default: default), DRY_RUN=true

5. Verify

make status

All pods should reach Running status within a few minutes.

Upgrade Procedure

1. Download new chart:

   CHART_VERSION="v24.09.28-d127c3d1"
   helm pull oci://us-docker.pkg.dev/cyberhaven-cd/external/charts/ci-stack-onprem --untar --version $CHART_VERSION
   cd ci-stack-onprem

2. Preview changes (Recommended):

   IMAGES_TAG=<new-tag> make diff

3. Dry-run (Required):

   IMAGES_TAG=<new-tag> INSTALL_TOKEN='<your-token>' make template DRY_RUN=true

4. Upgrade:

   IMAGES_TAG=<new-tag> INSTALL_TOKEN='<your-token>' make upgrade

5. Rollback if needed:

   helm rollback ci-stack-onprem <PREVIOUS-REVISION>

Migrating from values-overrides-<provider>.yaml configuration

Migration Mapping

Old Parameter	New Parameter	Notes
global.image.repository	global.customer.images.repository
global.image.tag	global.customer.images.tag	Also set via IMAGES_TAG env var
installToken	global.customer.installToken	Also set via INSTALL_TOKEN env var
captureBucketType	global.customer.captureBucket.type
captureBucket	global.customer.captureBucket.config
cacheBucketType	global.customer.cache.type
cacheBucketName	global.customer.cache.name
ingress	global.customer.ingress
serviceAccountAnnotations.dlp-coordinator	global.customer.provider.serviceAccount	Reuse existing dlp-coordinator SA

Identity Consolidation

Important: The new deployment consolidates all service accounts into a single identity:

• GCP: Reuse your existing dlp-coordinator service account as the consolidated CI stack service account
• AWS/Azure: Use workload identity federation via global.customer.saas.googleCredentials

Remove separate service accounts for dlp-tika and ci-scanner - these now use the consolidated identity.

Migration Steps

1. Backup: cp values-overrides-gcp.yaml values-overrides-gcp.yaml.backup
2. Configure: Use mapping table above to populate values/customer-values.yaml
3. Identity: Update your existing dlp-coordinator SA with permissions for all components (no new SA needed)
4. Deploy: Use new command format with Makefile

Makefile Commands

Required Environment Variables:

• IMAGES_TAG - Image tag (provided by Cyberhaven)
• INSTALL_TOKEN - Install token from dashboard

Optional Environment Variables:

• NAMESPACE - Target namespace (default: default)
• DRY_RUN=true - Dry-run only
• VALUES, ENCRYPTION_VALUES, EXTRA_VALUES - Additional values files

Commands:

• make help - Show all commands
• make upgrade - Install/upgrade release
• make diff - Preview changes
• make template - Render manifests
• make status - Show release and pod status
• make uninstall - Remove release

Examples:

# Dry-run
IMAGES_TAG=v1.2.3 INSTALL_TOKEN='{"dlp_host":"https://example.cyberhaven.io","install_token":"xyz"}' make template DRY_RUN=true

# Deploy
IMAGES_TAG=v1.2.3 INSTALL_TOKEN='{"dlp_host":"https://example.cyberhaven.io","install_token":"xyz"}' make upgrade

# Preview changes
IMAGES_TAG=v1.2.3 make diff

# Custom namespace
NAMESPACE=cyberhaven IMAGES_TAG=v1.2.3 INSTALL_TOKEN='<token>' make upgrade

Troubleshooting

Pods not starting: Check image pull secrets and registry access

kubectl describe pod <pod-name>

Ingress issues: Verify ingress controller and TLS configuration

kubectl describe ingress

Authentication errors: Verify workload identity configuration

For detailed troubleshooting steps, see Monitoring & Troubleshooting.

For support: Run make status, collect pod logs with kubectl logs <pod-name>, and contact Cyberhaven support.