Watson Deployment Guide

Multi-Cloud Support

Automatic Detection: The installation script automatically detects whether you're running on AWS EKS or GCP GKE and configures the appropriate cloud-native integrations.

Feature	AWS EKS	GCP GKE
Service Account Integration	IRSA (IAM Roles for Service Accounts)	Workload Identity
Default Storage Class	`gp3-xfs`	`standard-rwo`
Default Ingress Class	`alb` (AWS Load Balancer)	`gce` (Google Load Balancer)
IAM Permissions	ReadOnlyAccess Policy	Viewer Role

Prerequisites

1 Kubernetes Cluster Access

Ensure kubectl is installed and configured
Verify cluster access: kubectl cluster-info

2 Helm Installation

Helm 3.8+ is required
Install from: https://helm.sh/docs/intro/install/

3 Cloud-Specific IAM Setup

AWS EKS Setup

GCP GKE Setup

AWS EKS: Create an IAM role with IRSA (IAM Roles for Service Accounts) for secure AWS integration.

Trust Policy

Create a trust policy file trust-policy.json:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/oidc.eks.YOUR_REGION.amazonaws.com/id/YOUR_CLUSTER_OIDC_ID"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks.YOUR_REGION.amazonaws.com/id/YOUR_CLUSTER_OIDC_ID:sub": "system:serviceaccount:sherlocks:watson",
                    "oidc.eks.YOUR_REGION.amazonaws.com/id/YOUR_CLUSTER_OIDC_ID:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

Permissions Policy

Attach the AWS managed policy: ReadOnlyAccess

AWS CLI Commands

# Create the IAM role
aws iam create-role \
  --role-name watson-role \
  --assume-role-policy-document file://trust-policy.json

# Attach ReadOnly policy
aws iam attach-role-policy \
  --role-name watson-role \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

# Get the role ARN (save this for installation)
aws iam get-role --role-name watson-role --query 'Role.Arn' --output text

GCP GKE: Create a GCP Service Account with Workload Identity for secure GCP integration.

Enable Workload Identity

Ensure Workload Identity is enabled on your GKE cluster:

# Enable Workload Identity on existing cluster
gcloud container clusters update CLUSTER_NAME \
    --region=REGION \
    --workload-pool=PROJECT_ID.svc.id.goog

Create GCP Service Account

# Create GCP Service Account
gcloud iam service-accounts create watson-sa \
    --display-name="Watson Service Account" \
    --description="Service account for Watson application"

Grant Permissions

# Grant Viewer role (equivalent to AWS ReadOnlyAccess)
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:watson-sa@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/viewer"

Bind Workload Identity

# Allow the Kubernetes service account to impersonate the GCP service account
gcloud iam service-accounts add-iam-policy-binding \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[sherlocks/watson]" \
    watson-sa@PROJECT_ID.iam.gserviceaccount.com

Service Account Email: During installation, you'll need: watson-sa@PROJECT_ID.iam.gserviceaccount.com

Installation

Universal Installation

Works on both AWS EKS and GCP GKE with automatic detection:

bash <(curl -fsSL https://charts.sherlocks.info/sherlocksctl.sh)

Manual Download (Alternative)

curl -o sherlocksctl.sh https://charts.sherlocks.info/sherlocksctl.sh
chmod +x sherlocksctl.sh
./sherlocksctl.sh install

Configuration Prompts

The installation script will guide you through configuration options tailored to your cloud provider:

Basic Configuration

These prompts are the same for both cloud providers:

Release Name

Release name [watson]:

Description	Helm release name for the deployment
Default	`watson`
Mandatory	✅ Yes (can use default)

Cloud-Specific Service Account Configuration

AWS Configuration

GCP Configuration

AWS IAM Role ARN

AWS IAM Role ARN (for IRSA):

Description	AWS IAM Role ARN created in prerequisites
Mandatory	🚨 YES (Required for AWS integration)
Format	`arn:aws:iam::ACCOUNT_ID:role/watson-role`
Example	`arn:aws:iam::123456789012:role/watson-role`

GCP Service Account Email

GCP Service Account Email (for Workload Identity):

Description	GCP Service Account email created in prerequisites
Mandatory	🚨 YES (Required for GCP integration)
Format	`SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com`
Example	`watson-sa@my-project.iam.gserviceaccount.com`

Storage Configuration

AWS Storage

GCP Storage

Storage class [gp3-xfs]:

Default	`gp3-xfs`
Common Values	`gp2`, `gp3`, `gp3-xfs`, `io1`

Storage class [standard-rwo]:

Default	`standard-rwo`
Common Values	`standard-rwo`, `premium-rwo`, `balanced-persistent-disk`

Ingress Configuration

AWS ALB

GCP Load Balancer

Ingress class [alb]:

Common AWS ALB Annotations:

alb.ingress.kubernetes.io/scheme=internet-facing
alb.ingress.kubernetes.io/target-type=ip
alb.ingress.kubernetes.io/certificate-arn=your-cert-arn

Ingress class [gce]:

Common GCP Load Balancer Annotations:

kubernetes.io/ingress.global-static-ip-name=your-ip-name
kubernetes.io/ingress.allow-http=false
ingress.gcp.kubernetes.io/managed-certificates=your-cert-name

Environment Variables

These are the same for both cloud providers:

Encryption Key

ENCRYPTION_KEY (for data encryption):

Mandatory	🚨 YES
Example	Generate with `openssl rand -hex 32`

Basic Auth Credentials

BASIC_AUTH_USERNAME [admin]:

BASIC_AUTH_PASSWORD (will be visible):

Mandatory	🚨 Both Required
Note	Basic authentication is always enabled for security

Post-Installation

Verify Deployment

# Check pod status
kubectl get pods -n sherlocks

# Check service
kubectl get svc -n sherlocks

# Check ingress
kubectl get ingress -n sherlocks

Access Watson

🌍 Web Interface: https://your-hostname.com
🔐 Credentials: Use the basic auth username/password configured during installation

Troubleshooting

AWS Troubleshooting

GCP Troubleshooting

AWS-Specific Issues

IRSA Role Issues

# Check service account annotations
kubectl describe sa -n sherlocks watson

# Check pod environment variables
kubectl exec -n sherlocks watson-0 -- env | grep AWS

# Verify OIDC provider
aws eks describe-cluster --name CLUSTER_NAME --query cluster.identity.oidc

ALB Ingress Issues

# Check ALB controller logs
kubectl logs -n kube-system deployment/aws-load-balancer-controller

# Verify ingress events
kubectl describe ingress -n sherlocks watson

GCP-Specific Issues

Workload Identity Issues

# Check service account annotations
kubectl describe sa -n sherlocks watson

# Check pod environment variables
kubectl exec -n sherlocks watson-0 -- env | grep GOOGLE

# Verify Workload Identity binding
gcloud iam service-accounts get-iam-policy watson-sa@PROJECT_ID.iam.gserviceaccount.com

GCE Ingress Issues

# Check ingress controller logs
kubectl logs -n kube-system -l k8s-app=gce-ingress

# Verify load balancer creation
gcloud compute forwarding-rules list

Common Issues (Both Clouds)

Pod Not Starting

kubectl describe pod -n sherlocks watson-0
kubectl logs -n sherlocks watson-0

Health Check Failures

# Check if /health endpoint is accessible
kubectl exec -n sherlocks watson-0 -- curl localhost:8080/health

Table of Contents

Quick Start - Works on Both AWS EKS & GCP GKE!