Deploy the Operator

Once you've created a pool, installed the CLI, and verified your cluster permissions, you can deploy the AI Gateway Operator to your Kubernetes cluster. The Operator handles everything else — it connects to the Cequence control plane, deploys Armor, and manages the lifecycle of all components in your pool.

Prerequisites

• Kubernetes cluster access configured (kubectl working)
• A pool created in the portal (see Create a pool)
• The CLI installed and authenticated (see Install the CLI)
• Appropriate RBAC permissions in the cluster

Step-by-Step: Deployment

1. Verify Cluster Access

   # Check kubectl is configured
   kubectl cluster-info
   
   # Verify you can access the cluster
   kubectl get nodes

2. Initialize CLI Configuration

   # Set your tenant ID
   aigateway init --tenant <your-tenant-id> --pool-id <pool-id>
   
   # Authenticate
   aigateway login

3. Deploy the Operator

   Basic Installation:

   # Deploy to default namespace (from pool configuration)
   aigateway deploy install

   Installation with Options:

   # Deploy and wait for readiness
   aigateway deploy install --wait
   
   # Dry run to see what would be deployed
   aigateway deploy install --dry-run
   
   # Show processed manifests
   aigateway deploy install --dry-run --show-manifests

   Image and replica configuration go through the pool, not the CLI. Set the Operator image, Armor image, and replica count on the pool's Advanced tab in the portal — that keeps configuration in one place and survives upgrades. See Mirroring images to an internal registry.

   Skip Permission Checks:

   Use the --skip-permission-checks flag if you encounter permission errors like the following:

   [INFO] Performing comprehensive pre-flight validation...
   Error: failed to apply manifests: pre-flight validation failed: failed to check storage classes: storageclasses.storage.k8s.io is forbidden: User "user@example.com" cannot list resource "storageclasses" in API group "storage.k8s.io" at the cluster scope

   # Skip permission checks
   aigateway deploy install --skip-permission-checks

4. Monitor Deployment

   After the CLI deploys the Operator, it will automatically:

   • Connect to the Cequence control plane
   • Deploy the Armor gateway
   • Set up Redis (if configured for auto-install)
   • Configure ingress routing
   • Begin reporting health via heartbeat

   You can monitor progress with:

   # Check deployment status
   aigateway status
   
   # Watch status in real-time
   aigateway status --watch
   
   # Detailed status information
   aigateway status --verbose
   
   # View Operator logs
   aigateway logs
   
   # View events
   aigateway events
   
   # Monitor with comprehensive dashboard
   aigateway monitor

5. Verify Deployment

   # Check pods are running
   kubectl get pods -n <namespace>
   
   # Check services
   kubectl get svc -n <namespace>
   
   # Check ingress (if configured)
   kubectl get ingress -n <namespace>

   You can also verify from the UI:

   • Navigate to Private Cloud and select your pool
   • The pool status should show Active with a recent heartbeat timestamp
   • The Operator Status section displays version information and component health

What the Operator Deploys

After installation, the Operator automatically manages the following components in your cluster:

Component	What it does
Armor	Data plane gateway — routes and secures all agent traffic
Redis	Session state and caching — production: connects to your enterprise/managed Redis (manual mode). Dev/POV: runs in-cluster as a 3-node Sentinel HA cluster (auto-install)
Ingress	External routing rules for your configured hostname
SIEM Exporter	Audit event forwarding (if configured)

You do not need to deploy or configure these components manually. The Operator creates, updates, and monitors them based on your pool configuration.

Common Deployment Scenarios

Scenario 1: Standard Production Deployment

# Initialize and authenticate
aigateway init --tenant <your-tenant-id> --pool-id <your-pool-id>
aigateway login

# Deploy
aigateway deploy install

Scenario 2: Inspect the manifests before applying

aigateway deploy install --dry-run --show-manifests

Upgrading an Existing Deployment

The Operator can self-update when new versions are available. You can also trigger an upgrade manually:

# Upgrade to latest version
aigateway deploy upgrade

# Upgrade with specific options
aigateway deploy upgrade --wait

# Check what would be upgraded
aigateway deploy upgrade --dry-run

Uninstalling

# Remove AI Gateway from cluster
aigateway deploy uninstall

# Dry run to see what would be removed
aigateway deploy uninstall --dry-run

Warning: Uninstalling will delete all resources including the Operator, Armor, Redis, and any persistent data.

Troubleshooting Deployment

Issue: Deployment fails

# Check deployment status
aigateway status --verbose

# View error logs
aigateway logs --errors --since 10m

# Check Kubernetes events
aigateway events --critical

# Generate troubleshooting report
aigateway deploy troubleshoot

Issue: Pods not starting

# Check pod status
kubectl get pods -n <namespace>

# Describe problematic pod
kubectl describe pod <pod-name> -n <namespace>

# View pod logs
kubectl logs <pod-name> -n <namespace>

# Check events
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

Issue: Image pull errors

• Verify registry credentials secret exists:

  kubectl get secret regcred -n <namespace>

• Check registry credentials are correct
• Verify network access to container registry

Issue: Ingress not working

• Verify ingress controller is installed:

  kubectl get ingressclass

• Check ingress resource:

  kubectl get ingress -n <namespace>
  kubectl describe ingress <ingress-name> -n <namespace>

• Verify DNS configuration points to ingress

Issue: Operator not connecting (pool stays in Pending or Stale)

• Verify the Operator pod is running:

  kubectl get pods -n <namespace> -l app=ai-gateway-operator

• Check Operator logs for connectivity errors:

  kubectl logs -n <namespace> -l app=ai-gateway-operator

• Ensure outbound HTTPS access to the Cequence control plane is not blocked by firewall or network policy

Post-Deployment Verification

After successful deployment, verify:

1. All pods are running:

   kubectl get pods -n <namespace>
   # Should show: Operator, Armor, Redis (if auto-install), etc.

2. Services are created:

   kubectl get svc -n <namespace>

3. Operator is healthy and connected:

   aigateway status
   # Should show all components as healthy

   Or check the Private Pools page in the portal — your pool should show Active status with a recent heartbeat.

4. Logs are clean:

   aigateway logs --errors
   # Should show no errors

Tips

• Always use --wait in production to ensure deployment completes
• Use --dry-run first to verify configuration
• Monitor deployments with aigateway status --watch
• Keep CLI updated to latest version
• Use structured output (--json) for automation