Cloud Spectra Gateway User Guide

Three Tiers at a Glance

Cloud Spectra ships as a single appliance available in three tiers. Every tier is a Cloud Spectra Gateway, and each tier is a strict superset of the one below it -- Security includes everything in Network, and Enterprise includes everything in Security. Pick a tier by the capabilities you need; you can upgrade in place at any time.

Architecture

Overview

Cloud Spectra Gateway deploys as one or more EC2 instances managed by Auto Scaling Groups (one ASG per Availability Zone). Each instance runs the full Cloud Spectra software stack, providing NAT, load balancing, firewall inspection, HTTP proxy, AI gateway, and VPC transit management capabilities from a single appliance.

The gateway is deployed via a single CloudFormation stack. A Go-based Lambda function handles all custom resource lifecycle operations (create, update, delete) including VPC setup, ENI creation, route table management, and DNS zone provisioning.

graph TD
    IGW["AWS Internet Gateway"]
    subgraph AZ1["Availability Zone 1a"]
        GW1["Cloud Spectra Gateway
sNAT | dNAT | NLB
Firewall | Proxy | AI Gateway"]
        SUB1["Private Subnets
10.0.1.0/24"]
    end
    subgraph AZ2["Availability Zone 1b"]
        GW2["Cloud Spectra Gateway
sNAT | dNAT | NLB
Firewall | Proxy | AI Gateway"]
        SUB2["Private Subnets
10.0.2.0/24"]
    end
    subgraph AZ3["Availability Zone 1c"]
        GW3["Cloud Spectra Gateway
sNAT | dNAT | NLB
Firewall | Proxy | AI Gateway"]
        SUB3["Private Subnets
10.0.3.0/24"]
    end
    IGW --- GW1
    IGW --- GW2
    IGW --- GW3
    GW1 --- SUB1
    GW2 --- SUB2
    GW3 --- SUB3
    style IGW fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style GW1 fill:#d1fae5,stroke:#10b981,color:#065f46
    style GW2 fill:#d1fae5,stroke:#10b981,color:#065f46
    style GW3 fill:#d1fae5,stroke:#10b981,color:#065f46
    style SUB1 fill:#f1f5f9,stroke:#94a3b8,color:#475569
    style SUB2 fill:#f1f5f9,stroke:#94a3b8,color:#475569
    style SUB3 fill:#f1f5f9,stroke:#94a3b8,color:#475569

Multi-AZ deployment: each AZ has its own gateway instance, keeping traffic in-zone (up to 6 AZs supported)

Per-AZ Design

Each Availability Zone receives a dedicated set of resources:

• Cloud Spectra Subnet -- a /28 CIDR block (auto-selected or explicitly specified) inside the target VPC
• Elastic Network Interface (ENI) -- a stable private IP address that persists across instance replacements, vertical scaling, and failover events
• Auto Scaling Group -- manages exactly one instance (vertical scaling mode) or multiple instances (horizontal scaling with GWLB)
• Route table entry -- private subnets route 0.0.0.0/0 to the local AZ's Cloud Spectra ENI

This per-AZ architecture eliminates cross-AZ data transfer charges ($0.01/GB each way), which can represent significant savings at scale.

Traffic Flow

The following diagram shows how a typical outbound request traverses the Cloud Spectra gateway when both NAT and firewall features are enabled:

sequenceDiagram
    participant I as Private Instance
10.0.1.50
    participant NFT as nftables
L3/L4 Filtering
    participant S as Suricata IDS/IPS
Deep Packet Inspection
    participant NAT as sNAT Engine
    participant G as Internet
    I->>NFT: Outbound packet
    NFT->>S: NFQUEUE handoff
    S->>NFT: Verdict: ACCEPT
    NFT->>NAT: sNAT: 10.0.1.50 to EIP
    NAT->>G: Forwarded request
    G-->>NAT: Response
    NAT-->>NFT: de-NAT: EIP to 10.0.1.50
    NFT-->>S: NFQUEUE handoff
    S-->>NFT: Verdict: ACCEPT
    NFT-->>I: Deliver to instance

Outbound packet flow: nftables stateless rules first, then Suricata deep inspection via NFQUEUE, then NAT

graph LR
    subgraph FW["Firewall Inspection Pipeline"]
        direction LR
        A["Ingress
nftables"] -->|"NFQUEUE 0"| B["Suricata
IDS/IPS"]
        B -->|"ACCEPT"| C["Egress
nftables"]
        B -->|"DROP"| D["Blocked
+ Logged"]
    end
    style A fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style B fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style C fill:#d1fae5,stroke:#10b981,color:#065f46
    style D fill:#fecaca,stroke:#ef4444,color:#991b1b

Firewall inspection pipeline: nftables performs stateless L3/L4 filtering, Suricata handles deep packet inspection via NFQUEUE

Deployment

CloudFormation

Cloud Spectra Gateway is deployed via a single CloudFormation stack. The template creates all required resources: VPC (optional), subnets, ENIs, ASGs, IAM roles, security groups, Lambda functions, and Elastic IPs. The deployment process takes approximately 5-8 minutes.

Deployment Steps

1. Navigate to the AWS CloudFormation Console
2. Select Create stack and upload the Cloud Spectra Gateway template (or use the S3 URL provided by Cloud Spectra)
3. Configure the stack parameters (see table below)
4. Acknowledge the IAM capability checkbox
5. Create the stack and wait for CREATE_COMPLETE
6. Access the dashboard at the AccessElasticIp output URL

Key Parameters

Parameter	Default	Description
newOrExistingVpc	createNew	Create a new VPC or deploy into an existing one (selectExisting)
existingVpcId	(empty)	VPC ID when using selectExisting mode
availabilityZone1	a	Primary AZ suffix (required). Add availabilityZone2 through availabilityZone6 for multi-AZ HA
instance0000type	c6in.large	Initial EC2 instance type. See pricing
clientCidrBlock	0.0.0.0/0	CIDR allowed to access SSH (port 22) and dashboard (port 9443)
firewallPolicies	(empty)	Comma-separated AWS Network Firewall policy names for Suricata rule sync
enableGwlb	false	Enable Gateway Load Balancer for horizontal scaling across multiple instances
warmPoolDisabled	true	Set to false to enable warm pool for fast failover (~25 seconds)

Stack Outputs

Output	Description
AccessElasticIp	Dashboard URL: https://<EIP>:9443
AccessPrivateId1-6	ENI IDs per AZ -- use these as route table targets for private subnets
AccessPrivateIp1-6	Stable private IPs per AZ -- persist across instance replacements
SshPrivateKeyPath	SSM Parameter Store path to the SSH private key
VpcId	VPC ID (created or existing)

Deploying into an Existing VPC

Set newOrExistingVpc=selectExisting and provide existingVpcId. The stack creates Cloud Spectra subnets (/28 blocks) inside your VPC. After deployment, update your private subnet route tables to point 0.0.0.0/0 at the Cloud Spectra ENI for the corresponding AZ.

graph LR
    subgraph VPC["Your Existing VPC (10.0.0.0/16)"]
        subgraph PS["Your Private Subnet (10.0.1.0/24)
Route: 0.0.0.0/0 -> eni-cloudspectra-az1"]
            EC2["Your EC2 Instances"]
        end
        subgraph CS["Cloud Spectra Subnet (10.0.255.240/28)
auto-created"]
            GW["Cloud Spectra Gateway
sNAT | Firewall | NLB
eni-cloudspectra-az1"]
        end
    end
    EC2 -->|"0.0.0.0/0"| GW
    GW -->|"sNAT"| INET["Internet"]
    style EC2 fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style GW fill:#d1fae5,stroke:#10b981,color:#065f46
    style INET fill:#fef3c7,stroke:#f59e0b,color:#92400e

Cloud Spectra deploys into a small /28 subnet inside your existing VPC

Dashboard

The web dashboard is accessible at https://<EIP>:9443. Default credentials use the admin username with the password set during initial login (stored in SSM Parameter Store).

Dashboard Sections

• Overview -- instance health, traffic throughput, CPU/memory utilization, active feature summary
• Resources -- AWS resources created by the stack (ENIs, ASGs, Route53 zones, IAM roles) with direct links to the AWS Console
• Settings -- enable/disable features: NAT, Firewall, NLB Replacement, HTTP Proxy, AI Gateway, VPC Transit Manager
• Instance Types -- interactive pricing calculator with per-instance-type costs and network bandwidth comparison
• Instances -- per-instance status showing type, lifecycle (spot/on-demand), AZ, public/private IPs, and vCPU/memory details
• Availability Zones -- add or remove AZs dynamically, view per-AZ status
• Accounts -- manage cross-account VPC access for transit manager

All dashboard actions are also available via the REST API at https://<EIP>:9443/api/.

NAT Gateway NAT Tier

Source NAT (sNAT)

Source NAT is enabled by default. All outbound traffic from private subnets is translated to the Cloud Spectra instance's Elastic IP address using kernel-level nftables masquerade rules. This provides the same functionality as the AWS managed NAT Gateway with zero per-GB data processing fees.

Cost Comparison

Service	Hourly Cost	Per-GB Cost	1 TB/month
AWS NAT Gateway	$0.045/hr	$0.045/GB	$77.40
Cloud Spectra Gateway (c6in.large)	$0.1134/hr	$0.00/GB	$81.65
Cloud Spectra Gateway (c6in.large) @ 5 TB/mo	$0.1134/hr	$0.00/GB	$81.65
AWS NAT Gateway @ 5 TB/mo	$0.045/hr	$0.045/GB	$257.40

Configure via dashboard (Settings) or API:

PUT /api/cloudspectra/nat-gateway
{"enable": true}

Port Forwarding (dNAT)

Destination NAT allows forwarding external ports on the gateway's Elastic IP to internal instances. Rules are implemented using nftables DNAT and take effect within 60 seconds of configuration.

Configure via dashboard or API:

PUT /api/cloudspectra/port-forwarding
[
  {
    "enabled": true,
    "protocol": "tcp",
    "externalPort": 8080,
    "targetIp": "10.0.1.50",
    "targetPort": 80,
    "description": "Web server"
  },
  {
    "enabled": true,
    "protocol": "tcp",
    "externalPort": 3306,
    "targetIp": "10.0.1.100",
    "targetPort": 3306,
    "description": "MySQL database"
  }
]

Field	Type	Description
enabled	boolean	Toggle this rule on/off without deleting it
protocol	string	tcp or udp
externalPort	integer	Port on the gateway's public IP (1-65535)
targetIp	string	Private IP of the destination instance
targetPort	integer	Port on the destination instance (1-65535)
description	string	Human-readable label for this rule

NLB Replacement Network Tier

IPVS L4 Load Balancing

Cloud Spectra syncs your existing AWS NLB configuration (listeners, target groups, health checks) and programs equivalent IPVS (IP Virtual Server) kernel rules. Traffic is load-balanced at Layer 4 in the Linux kernel with zero NLB hourly or LCU charges.

graph LR
    subgraph AWS["AWS NLB (config source only)"]
        NLB["Listener :443 TCP
Target Group:
10.0.1.10:443
10.0.1.20:443
10.0.1.30:443"]
    end
    subgraph CG["Cloud Spectra Gateway (traffic handler)"]
        IPVS["IPVS Virtual Service
:443 TCP
Scheduler: round-robin"]
        RS1["Real Server 10.0.1.10:443"]
        RS2["Real Server 10.0.1.20:443"]
        RS3["Real Server 10.0.1.30:443"]
    end
    NLB -- "sync every 10s" --> IPVS
    IPVS --> RS1
    IPVS --> RS2
    IPVS --> RS3
    CLIENT["Clients"] --> IPVS
    style NLB fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style IPVS fill:#d1fae5,stroke:#10b981,color:#065f46
    style RS1 fill:#f1f5f9,stroke:#94a3b8,color:#475569
    style RS2 fill:#f1f5f9,stroke:#94a3b8,color:#475569
    style RS3 fill:#f1f5f9,stroke:#94a3b8,color:#475569
    style CLIENT fill:#fef3c7,stroke:#f59e0b,color:#92400e

NLB configuration is synced to IPVS; client traffic flows through Cloud Spectra, not the NLB

How It Works

1. The cloudspectra_network_load_balancer service polls the specified NLB every 10 seconds
2. Listener configurations and target group memberships are read via the AWS ELBv2 API
3. IPVS virtual services and real servers are programmed in the Linux kernel
4. Health check results from the NLB target groups determine which backends receive traffic

Enable via dashboard: Settings -- NLB, or API:

PUT /api/cloudspectra/nlb-gateway
{"enable": true, "loadBalancer": "my-nlb-name"}

TLS Termination

When the NLB has TLS listeners, Cloud Spectra automatically handles TLS termination using HAProxy. Certificates are exported from AWS Certificate Manager (ACM) and installed into HAProxy, which terminates TLS and forwards plaintext traffic to IPVS backends.

Certificate Management

• ACM certificates referenced by NLB TLS listeners are automatically exported
• Certificates are renewed and rotated automatically as ACM renews them
• HAProxy is reloaded without downtime when certificates change
• Both RSA and ECDSA certificates are supported

PUT /api/cloudspectra/nlb-gateway
{
  "enable": true,
  "loadBalancer": "my-nlb-name",
  "tlsListeners": true
}

EIP Failover

Cloud Spectra manages a pool of Elastic IPs distributed across instances via secondary private IPs. If an instance fails, its EIPs are reassigned to healthy instances within seconds -- no DNS propagation delay required. The EIP manager runs on the master instance (the instance with the lowest ordinal across all AZs).

graph TB
    subgraph NORMAL["Normal Operation"]
        direction LR
        E1N["EIP-1"] --> A1N["Instance AZ-a
10.0.1.10"]
        E2N["EIP-2"] --> B1N["Instance AZ-b
10.0.2.10"]
        D1N["*.gw.example.com
-> 10.0.1.10, 10.0.2.10"]
    end
    subgraph FAIL["After AZ-a Failure"]
        direction LR
        E1F["EIP-1 (reassigned)"] --> B1F["Instance AZ-b
10.0.2.10"]
        E2F["EIP-2"] --> B2F["Instance AZ-b
10.0.2.10"]
        D1F["*.gw.example.com
-> 10.0.2.10 only"]
    end
    NORMAL --> |"AZ-a fails"| FAIL
    style E1N fill:#dbeafe,stroke:#2563eb
    style E2N fill:#dbeafe,stroke:#2563eb
    style E1F fill:#fecaca,stroke:#ef4444
    style E2F fill:#dbeafe,stroke:#2563eb
    style A1N fill:#d1fae5,stroke:#10b981
    style B1N fill:#d1fae5,stroke:#10b981
    style B1F fill:#d1fae5,stroke:#10b981
    style B2F fill:#d1fae5,stroke:#10b981

EIP failover: EIPs from failed instances are reassigned to healthy instances within seconds

Configuration

EIP pool size and failover behavior are configured through the ASG settings:

PUT /api/cloudspectra/asg
{
  "elasticIps": 2,
  "enableEipFailover": true
}

Failover Behavior

• Each EIP is associated with a secondary private IP on the target instance's ENI
• On failure detection, EIPs are moved to healthy instances via the EC2 API
• Route53 DNS A records are updated automatically to reflect the new IP assignments
• Stale per-AZ DNS records for failed instances are deleted
• Typical failover time: under 10 seconds (API call latency only, no DNS TTL wait)

Per-AZ DNS

Cloud Spectra creates and manages Route53 private hosted zones that map DNS names to per-AZ gateway private IPs. This enables zone-aware traffic routing, ensuring clients connect to their local AZ's gateway instance.

DNS Records Created

Record	Example	Resolves To
Wildcard (all AZs)	*.gw.example.com	All healthy gateway private IPs (round-robin)
Per-AZ	us-east-1a.gw.example.com	AZ-a gateway private IP only
Per-AZ	us-east-1b.gw.example.com	AZ-b gateway private IP only

Use Cases

• HTTP Proxy -- configure clients with the per-AZ DNS name to avoid cross-AZ charges
• AI Gateway -- route LLM API calls to the local AZ's gateway
• NLB Replacement -- use the wildcard DNS as the service endpoint

DNS configuration is managed automatically. The hosted zone name is derived from the stack name. Override via API:

PUT /api/cloudspectra/dns
{
  "hostedZoneName": "gw.example.com",
  "ttl": 10
}

Scaling

Vertical Scaling

Cloud Spectra can automatically change the EC2 instance type based on CPU utilization, memory usage, and ENA packet-drop thresholds -- with zero downtime. The ASG launches a replacement instance of the new type, waits for it to initialize, then terminates the old instance. The ENI (and its private IP) remains attached throughout, so no route table changes are needed.

graph TD
    S1["c6in.large
2 vCPU | 5 Gbps
~$82/mo"]
    S2["c6in.xlarge
4 vCPU | 12.5 Gbps
~$163/mo"]
    S3["c6in.2xlarge
8 vCPU | 25 Gbps
~$326/mo"]
    S1 -->|"CPU > threshold for 5 min
zero-downtime swap"| S2
    S2 -->|"CPU > threshold for 5 min"| S3
    S3 -->|"CPU < 30% for 15 min
cost optimization"| S2
    S2 -->|"CPU < 30% for 15 min"| S1
    style S1 fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style S2 fill:#d1fae5,stroke:#10b981,color:#065f46
    style S3 fill:#fef3c7,stroke:#f59e0b,color:#92400e

Vertical scaling: instance type changes automatically based on load thresholds

Configuration

PUT /api/cloudspectra/asg
{
  "mode": "single",
  "enableAutoScaleUpDown": true,
  "instanceTypeList": ["c6in.large", "c6in.xlarge", "c6in.2xlarge", "c6in.4xlarge"],
  "cpuThreshold": 70,
  "memoryThreshold": 85,
  "packetDropsThreshold": 100,
  "pollIntervalSeconds": 60,
  "metricWindowSeconds": 300
}

Field	Default	Description
mode	single	single for vertical scaling, multi for horizontal
enableAutoScaleUpDown	false	Enable automatic instance type changes
instanceTypeList	[]	Ordered list of instance types [smallest ... largest]
cpuThreshold	80	CPU % above which scale-up is triggered (0 = disabled)
memoryThreshold	85	Memory % above which scale-up is triggered (0 = disabled)
packetDropsThreshold	0	ENA packet drops/s above which scale-up triggers (0 = disabled)
pollIntervalSeconds	60	How often metrics are sampled (1-300)
metricWindowSeconds	300	Averaging window for scale decisions (10-3600)

Horizontal Scaling (GWLB)

For workloads exceeding single-instance capacity, enable GWLB-based horizontal scaling. Multiple Cloud Spectra instances share traffic via AWS Gateway Load Balancer using transparent GENEVE tunnels.

graph TB
    subgraph PS["Private Subnets"]
        A["Instance A
10.0.1.10"]
        B["Instance B
10.0.1.20"]
        C["Instance C
10.0.1.30"]
    end
    subgraph GWLB["GWLB Layer"]
        EP1["GWLB Endpoint AZ-a
vpce-xxx"]
        EP2["GWLB Endpoint AZ-b
vpce-yyy"]
    end
    subgraph ASG["Cloud Spectra ASG (mode=multi)"]
        C1["Cloud Spectra #1
AZ-a"]
        C2["Cloud Spectra #2
AZ-a"]
        C3["Cloud Spectra #3
AZ-b"]
    end
    A --> EP1
    B --> EP1
    C --> EP2
    EP1 --> C1
    EP1 --> C2
    EP2 --> C3
    style EP1 fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style EP2 fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style C1 fill:#d1fae5,stroke:#10b981,color:#065f46
    style C2 fill:#d1fae5,stroke:#10b981,color:#065f46
    style C3 fill:#d1fae5,stroke:#10b981,color:#065f46
    style A fill:#f1f5f9,stroke:#94a3b8
    style B fill:#f1f5f9,stroke:#94a3b8
    style C fill:#f1f5f9,stroke:#94a3b8

Horizontal scaling: GWLB distributes traffic across multiple Cloud Spectra instances via GENEVE tunnels

Enable via CloudFormation parameter enableGwlb=true, then configure the ASG:

PUT /api/cloudspectra/asg
{
  "mode": "multi",
  "minInstances": 2,
  "maxInstances": 10,
  "cpuThreshold": 70
}

Mixed Instance Policy

When horizontal scaling is enabled, you can configure a mixed instance policy to combine Spot and On-Demand instances for cost optimization:

PUT /api/cloudspectra/asg
{
  "mode": "multi",
  "mixedInstancesPolicy": {
    "spotAllocationStrategy": "capacity-optimized",
    "onDemandBaseCapacity": 1,
    "onDemandPercentageAboveBaseCapacity": 0,
    "instanceTypes": ["c6in.xlarge", "c6in.2xlarge", "c7i.xlarge"]
  }
}

Field	Description
onDemandBaseCapacity	Number of On-Demand instances always running (recommended: at least 1)
onDemandPercentageAboveBaseCapacity	% of additional capacity that should be On-Demand (0 = all Spot)
spotAllocationStrategy	capacity-optimized (recommended) or lowest-price
instanceTypes	Instance types eligible for the Spot pool

Warm Pool

The warm pool maintains pre-initialized instances in a stopped state, ready to replace failed instances rapidly. When an instance fails, the warm pool instance starts immediately -- skipping the full AMI boot and initialization sequence.

Performance

Scenario	Without Warm Pool	With Warm Pool
Instance replacement	3-5 minutes	~25 seconds
Vertical scale (type change)	3-5 minutes	~25 seconds

Enable via CloudFormation parameter warmPoolDisabled=false.

Firewall Security Tier

nftables Stateless Rules

Cloud Spectra uses nftables as the primary packet filtering engine. All traffic passes through nftables rules for L3/L4 (IP address, port, protocol) stateless filtering before reaching Suricata for deep packet inspection.

Rule Types

• 5-tuple rules -- match on source/destination IP, source/destination port, and protocol (TCP/UDP/ICMP)
• CIDR-based blocking -- block or allow entire IP ranges
• Port-based filtering -- restrict outbound access to specific ports
• Connection tracking -- stateful tracking of established connections

nftables rules are derived from AWS Network Firewall 5-tuple rule groups. Cloud Spectra translates them into native nftables syntax for kernel-level performance.

Suricata IDS/IPS

Cloud Spectra runs Suricata inline via NFQUEUE mode for deep packet inspection. Rules are synced from AWS Network Firewall policies -- you manage rules in the AWS console, and Cloud Spectra enforces them at the instance level.

graph LR
    subgraph AWS["AWS Network Firewall Console"]
        P["Firewall Policy"]
        RG1["Stateful Rule Group
(Suricata-compatible rules)"]
        RG2["Domain List Rule Group
(HTTP_HOST + TLS_SNI)"]
        RG3["5-Tuple Rule Group
(L3/L4 stateless rules)"]
        P --- RG1
        P --- RG2
        P --- RG3
    end
    subgraph CG["Cloud Spectra Gateway"]
        RF["/etc/suricata/rules/
aws-firewall.rules
et-open.rules"]
        SE["Suricata Engine
hot-reload via
unix socket"]
        NF["nftables
5-tuple rules"]
        RF --> SE
    end
    AWS -- "sync every 60s" --> RF
    AWS -- "sync every 60s" --> NF
    style P fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style RG1 fill:#f1f5f9,stroke:#94a3b8
    style RG2 fill:#f1f5f9,stroke:#94a3b8
    style RG3 fill:#f1f5f9,stroke:#94a3b8
    style RF fill:#d1fae5,stroke:#10b981,color:#065f46
    style SE fill:#d1fae5,stroke:#10b981,color:#065f46
    style NF fill:#d1fae5,stroke:#10b981,color:#065f46

Firewall rules managed in the AWS console, enforced by Cloud Spectra's Suricata engine and nftables

Key Benefits

• No firewall endpoints required -- saves $0.395/hr per AZ (over $850/month for 3 AZs)
• Same rule management experience -- use the AWS Network Firewall console, CLI, or Terraform to manage rules
• Hot-reload -- rule changes are detected and applied without restarting Suricata or dropping connections
• Multiple policies -- specify multiple firewall policy names for layered rule sets

Enable via CloudFormation parameter firewallPolicies or dashboard. Configuration via API:

PUT /api/cloudspectra/firewall-gateway
{
  "enable": true,
  "firewallPolicies": ["my-fw-policy", "baseline-rules"]
}

Domain Filtering

AWS Network Firewall domain list rule groups are automatically translated to Suricata content-match rules. Cloud Spectra supports both filtering modes:

Mode	Behavior	Use Case
DENYLIST	Block specified domains, allow everything else	Block known-bad or unwanted domains
ALLOWLIST	Allow specified domains, block everything else (strict default-deny)	Restrict access to approved domains only

Domain matching inspects both HTTP Host headers (plaintext HTTP) and TLS SNI fields (HTTPS). Wildcard patterns are supported (e.g., *.example.com).

ET Open Threat Detection

Community-maintained IDS/IPS signatures from Emerging Threats Open provide broad threat coverage with 30,000+ rules (BSD licensed). Categories include:

• Malware command-and-control (C2) callbacks
• Exploit kit landing pages and payloads
• Trojan and botnet activity
• Phishing and credential theft attempts
• Known-malicious IP addresses and domains
• Protocol anomaly detection

Enable via API:

PUT /api/cloudspectra/firewall-gateway
{
  "enable": true,
  "firewallPolicies": ["my-policy"],
  "threatDetectionEnabled": true,
  "threatDetectionUpdateIntervalHours": 24
}

Update Mechanism

• Rules are pre-cached in the AMI for instant coverage on first boot -- no internet access required for initial protection
• Auto-updates check rules.emergingthreats.net at the configured interval (default: 24 hours)
• Updates are applied via Suricata hot-reload -- no traffic interruption
• Failed updates do not affect existing rules; the previous ruleset remains active

L7 HTTP Proxy Security Tier

Cloud Spectra runs a distributed Squid HTTP proxy with NCSA authentication on every gateway instance. All instances share the same configuration via SSM Parameter Store -- update once in the dashboard, and all instances pick up the change within 60 seconds.

graph TB
    subgraph Client["Client Instance (AZ-a)"]
        ENV["export http_proxy=
http://user:pass@
us-east-1a.gw.example.com:1080"]
    end
    subgraph DNS["Per-AZ DNS Resolution"]
        D2["us-east-1a.gw.example.com
-> 10.0.1.10 (local AZ)"]
    end
    subgraph CG["Cloud Spectra Gateway AZ-a"]
        SQ["Squid Proxy
Port 1080
NCSA auth (bcrypt)
ACL: RFC1918 nets"]
    end
    Client --> DNS
    DNS --> CG
    CG --> INET["Internet"]
    style ENV fill:#f1f5f9,stroke:#94a3b8
    style SQ fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style INET fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style D2 fill:#dbeafe,stroke:#2563eb

HTTP proxy with per-AZ DNS: clients connect to their local AZ's proxy to avoid cross-AZ charges

Configuration

Enable via Settings -- L7 HTTP Proxy in the dashboard, or API:

PUT /api/cloudspectra/web-proxy-gateway
{
  "enable": true,
  "port": 1080,
  "username": "proxyuser",
  "password": "securepassword123"
}

Client Configuration

The dashboard shows DNS names and ready-to-copy environment variable commands. For zone-aware routing (recommended):

# Linux/macOS -- use per-AZ DNS to stay in-zone
export http_proxy=http://proxyuser:pass@us-east-1a.gw.example.com:1080
export https_proxy=http://proxyuser:pass@us-east-1a.gw.example.com:1080
export no_proxy=169.254.169.254,10.0.0.0/8

# Or use the wildcard DNS for round-robin across AZs
export http_proxy=http://proxyuser:pass@proxy.gw.example.com:1080

Features

• NCSA authentication -- bcrypt-hashed passwords stored in SSM (never plaintext)
• ACL enforcement -- only RFC1918 source IPs are allowed to connect
• HTTPS tunneling -- CONNECT method support for TLS passthrough
• Access logging -- all requests logged with timestamp, source IP, URL, and response code
• Per-AZ DNS -- use zone-specific DNS names to eliminate cross-AZ data transfer costs

Cloud Spectra AI Gateway Security Tier

The Cloud Spectra AI Gateway is a reverse-proxy for LLM API calls that provides centralized access control, response caching, token counting, and audit logging. It presents an OpenAI-compatible API endpoint and routes requests to OpenAI, Anthropic, or AWS Bedrock based on the model name.

graph LR
    subgraph Apps["Your Applications"]
        A1["App 1
GPT-4"]
        A2["App 2
Claude"]
        A3["App 3
Bedrock"]
    end
    subgraph CG["Cloud Spectra AI Gateway
Port 8080"]
        RT["Model Router"]
        CA["Response Cache
(15% of system RAM)"]
        AU["Audit Log"]
        TK["Token Counter"]
    end
    subgraph UP["Upstream Providers"]
        OA["OpenAI API"]
        AN["Anthropic API"]
        BR["AWS Bedrock"]
    end
    A1 --> RT
    A2 --> RT
    A3 --> RT
    RT --> CA
    CA --> OA
    CA --> AN
    CA --> BR
    RT --> AU
    RT --> TK
    style RT fill:#d1fae5,stroke:#10b981,color:#065f46
    style CA fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style AU fill:#f1f5f9,stroke:#94a3b8
    style TK fill:#f1f5f9,stroke:#94a3b8
    style OA fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style AN fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style BR fill:#fef3c7,stroke:#f59e0b,color:#92400e

Cloud Spectra AI Gateway: unified endpoint for multiple LLM providers with caching and audit

Provider Routing

The gateway automatically routes requests based on the model name in the request body:

Model Prefix	Provider	Example Models
gpt-*, o1-*, default	OpenAI	gpt-4o, gpt-4-turbo, o1-preview
claude*, anthropic/*	Anthropic	claude-sonnet-4-20250514, claude-3-5-haiku-20241022
bedrock/*, amazon.*, us.*	AWS Bedrock	bedrock/anthropic.claude-3, amazon.titan-text-lite

Configuration

PUT /api/cloudspectra/ai-gateway
{
  "enable": true,
  "port": 8080,
  "defaultProvider": "openai",
  "cacheEnabled": true,
  "cacheTtlSeconds": 3600,
  "auditLogEnabled": true,
  "allowedModels": ["gpt-4o", "claude-sonnet-4-20250514"],
  "bedrockRegion": "us-east-1",
  "maxRequestBodyBytes": 1048576,
  "maxResponseBodyBytes": 10485760
}

Client Usage

# Point your OpenAI SDK at the Cloud Spectra AI Gateway
export OPENAI_BASE_URL=http://us-east-1a.gw.example.com:8080/v1

# Requests are transparently proxied to the configured provider
curl http://us-east-1a.gw.example.com:8080/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Features

• Response caching -- identical prompts return cached responses instantly, reducing API costs and latency. Cache uses 15% of system RAM with configurable TTL
• Semantic caching -- fuzzy-match prompts that are semantically similar (configurable similarity threshold, default 0.90)
• Model allowlisting -- restrict which models can be used (empty list = all models allowed)
• Token counting -- track prompt and completion tokens per request for cost monitoring
• Audit logging -- log all requests with model, token counts, latency, and cache hit/miss status
• Request size limits -- configurable maximum request and response body sizes
• Bedrock SigV4 signing -- automatic AWS Signature V4 signing for Bedrock requests using the instance's IAM role
• Per-AZ DNS -- use zone-specific DNS names to avoid cross-AZ data transfer

Transit Manager Enterprise Tier

The Transit Manager discovers VPCs across multiple AWS accounts and regions, then creates and manages VPC peering connections to form a full mesh network. It replaces AWS Transit Gateway with free VPC peering -- eliminating both hourly attachment fees and per-GB data processing charges.

VPC Peering Mesh

graph TD
    subgraph A["Account A (Hub)"]
        V1["VPC-1 (10.1.0.0/16)
Cloud Spectra Gateway"]
        V4["VPC-4 (10.4.0.0/16)"]
    end
    subgraph B["Account B (Spoke)"]
        V2["VPC-2 (10.2.0.0/16)"]
    end
    subgraph C["Account C (Spoke)"]
        V3["VPC-3 (10.3.0.0/16)"]
    end
    V1 <-->|"pcx-aaa"| V2
    V1 <-->|"pcx-bbb"| V3
    V1 <-->|"pcx-ccc"| V4
    V2 <-->|"pcx-ddd"| V3
    V2 <-->|"pcx-eee"| V4
    V3 <-->|"pcx-fff"| V4
    COST["Full mesh: 4 VPCs = 6 peering connections
Cost: $0/hr + $0/GB
vs Transit Gateway: $0.05/hr per attachment + $0.02/GB"]
    style V1 fill:#d1fae5,stroke:#10b981,color:#065f46
    style V2 fill:#dbeafe,stroke:#2563eb,color:#1e40af
    style V3 fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style V4 fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style COST fill:#f1f5f9,stroke:#94a3b8,color:#475569

Full-mesh VPC peering: zero hourly and per-GB data-plane costs, fully automated route propagation

How It Works

1. VPC Discovery -- scans all configured accounts and regions for VPCs
2. Peering Creation -- creates VPC peering connections between all discovered VPCs
3. Auto-Accept -- accepts peering requests automatically using cross-account IAM roles
4. Route Propagation -- adds routes for peer VPC CIDRs to all route tables in each VPC
5. Continuous Reconciliation -- monitors for new VPCs and missing routes, repairs automatically

Configuration

PUT /api/cloudspectra/transit-gateway
{
  "enable": true,
  "peerVpcs": true,
  "managedAccountIds": ["111111111111", "222222222222", "333333333333"],
  "managedRegions": ["us-east-1", "us-west-2", "eu-west-1"]
}

Cost Comparison (10 VPCs across 3 accounts)

Service	Monthly Fixed Cost	Per-GB Cost	10 TB/month Total
AWS Transit Gateway	$360 (10 attachments)	$0.02/GB	$560
Cloud Spectra Transit Manager	$0	$0	$0

Cross-Account Setup

To manage VPCs in other AWS accounts, deploy a spoke IAM role in each target account. This role grants the Cloud Spectra Gateway's master account permission to discover VPCs, create peering connections, and manage routes.

Setup Steps

1. In the Cloud Spectra dashboard, navigate to Accounts and click Add Account
2. Enter the target AWS account ID
3. Download the cross-account CloudFormation template or IAM policy
4. Deploy the template in the target account (creates the spoke IAM role)
5. Click Verify to confirm the role is accessible

Cross-Account Template

The cross-account template creates a single IAM role with the following permissions:

• ec2:DescribeVpcs, ec2:DescribeSubnets, ec2:DescribeRouteTables -- VPC discovery
• ec2:CreateVpcPeeringConnection, ec2:AcceptVpcPeeringConnection -- peering management
• ec2:CreateRoute, ec2:DeleteRoute -- route propagation

The role uses an external ID and is scoped to the Cloud Spectra Gateway's master account for security.

API

# Add a spoke account
POST /api/cloudspectra/operational/accounts
{"accountId": "222222222222"}

# Get the cross-account CloudFormation stack for an account
GET /api/cloudspectra/operational/accounts/cross-account-stack?accountId=222222222222

# Get the cross-account IAM policy document
GET /api/cloudspectra/operational/accounts/cross-account-policy?accountId=222222222222

# Verify cross-account access
POST /api/cloudspectra/operational/cross-account-iam
{"accountId": "222222222222"}

Operational Guide

Service Management

Cloud Spectra Gateway runs as a set of systemd services on each instance. All services are enabled by default and start automatically on boot.

Service	Description	Required
cloudspectra_gateway_server	Dashboard and REST API server (port 9443 via nginx)	Yes
cloudspectra_bootstrap	First-boot initialization, auto-upgrade, ENI attachment	Yes
cloudspectra_startup	System configuration, sNAT rules, route setup	Yes
cloudspectra_basic_features	Core networking: sNAT, dNAT, EIP management, DNS	Yes
cloudspectra_autoscale_updown	Vertical scaling metric collection and ASG updates	No
cloudspectra_network_load_balancer	NLB sync and IPVS/HAProxy management	No
cloudspectra_firewall_sync	AWS Network Firewall rule sync and Suricata management	No
cloudspectra_transit_manager	VPC discovery, peering, and route propagation	No
cloudspectra_ai_gateway	LLM reverse proxy (port 8080)	No
cloudspectra_node_exporter	Prometheus metrics exporter	No
cloudspectra_vpc_peering_connections_stats	VPC peering connection health monitoring	No
cloudspectra_warm_pool_watcher	Warm pool lifecycle hook handler	No
cloudspectra_gwlbtun	GENEVE tunnel handler for GWLB mode	No

Common Service Commands

# Check status of a service
systemctl status cloudspectra_gateway_server

# View recent logs for a service
journalctl -u cloudspectra_firewall_sync --since "1 hour ago"

# Follow live logs
journalctl -u cloudspectra_basic_features -f

# Restart a service (configuration is re-read from SSM)
systemctl restart cloudspectra_network_load_balancer

# View all Cloud Spectra services
systemctl list-units 'cloudspectra_*'

Log Locations

All Cloud Spectra services log to journald by default. Logs are also written to /var/log/cloudspectra/ via logrotate.

Log	Location	Description
Service logs	journalctl -u cloudspectra_*	All service output (structured JSON via slog)
Suricata alerts	/var/log/suricata/eve.json	IDS/IPS alert events in EVE JSON format
Suricata fast log	/var/log/suricata/fast.log	One-line alert summaries
Squid access log	/var/log/squid/access.log	HTTP proxy request log
HAProxy log	/var/log/haproxy.log	TLS termination and L4 load balancing events
nginx access log	/var/log/nginx/access.log	Dashboard HTTPS reverse proxy log

Log Levels

All Cloud Spectra services use structured logging (slog) with configurable levels. Adjust log verbosity at runtime without restarting services:

# View current log levels for all services
GET /api/cloudspectra/operational/log-levels

# Set a service to debug level
PUT /api/cloudspectra/operational/log-levels
{"service": "firewallSync", "level": "debug"}

# Set global log level (affects all services)
PUT /api/cloudspectra/operational/log-levels
{"service": "", "level": "info"}

Level	Usage
debug	Per-poll/per-request detail, packet traces, AWS API calls
info	Lifecycle events: startup, config changes, state transitions (default)
warn	Recoverable errors, degraded-mode fallbacks
error	Failures that affect correctness and require attention

CloudWatch Metrics

Cloud Spectra publishes custom CloudWatch metrics for monitoring and alerting:

Metric	Namespace	Description
CPUUtilization	CloudSpectra/Gateway	Current CPU utilization percentage
MemoryUtilization	CloudSpectra/Gateway	Current memory utilization percentage
PacketDrops	CloudSpectra/Gateway	ENA packet drops per second
ActiveConnections	CloudSpectra/Gateway	Number of active NAT/proxy connections
BytesProcessed	CloudSpectra/Gateway	Total bytes processed through NAT/proxy

Metrics are viewable in the AWS CloudWatch console and through the dashboard's Overview page. Use CloudWatch Alarms to trigger notifications based on these metrics.

Auto-Upgrade

Cloud Spectra Gateway supports automatic software upgrades on instance boot. When a new version is available, the bootstrap service downloads and installs the updated package before starting other services.

How It Works

1. On boot, cloudspectra_bootstrap checks S3 for the latest package version
2. If the installed version differs from the target version, it downloads the new .deb package
3. The package checksum (SHA-256) is verified before installation
4. The package is installed via dpkg
5. The bootstrap process re-executes itself so the new binary takes over
6. Auto-upgrade runs at most once per boot (tracked via a lock file in /run/)

Upgrade Safety

• Atomic -- the new package replaces the old one in a single dpkg transaction
• Verified -- SHA-256 checksum validation prevents corrupted installs
• Idempotent -- re-running bootstrap after upgrade is a no-op (lock file prevents loops)
• Rollback -- if the new version fails to start, the ASG health check will launch a replacement from the warm pool

Security Model

IAM Permissions

Cloud Spectra Gateway uses two IAM roles with least-privilege permissions:

Instance Role (EC2)

Attached to the Cloud Spectra EC2 instances. Permissions include:

• SSM Parameter Store -- read/write configuration parameters (scoped to the stack's namespace)
• EC2 -- describe instances, ENIs, route tables, subnets, VPCs; attach/detach ENIs; modify instance attributes; manage EIPs
• Auto Scaling -- describe and update ASG settings, complete lifecycle hooks
• ELBv2 -- describe load balancers, target groups, and listeners (for NLB sync)
• Network Firewall -- describe firewall policies and rule groups (for Suricata sync)
• Route53 -- manage hosted zones and DNS records
• STS -- assume cross-account spoke roles (for transit manager)
• ACM -- export certificates (for TLS termination)
• CloudWatch -- publish custom metrics

Lambda Role (CloudFormation Custom Resources)

Used by the CloudFormation custom resource handler Lambda. Permissions include:

• EC2 -- create/delete subnets, ENIs, route table entries, security groups; manage GWLB resources
• Route53 -- create/delete hosted zones
• SSM -- create/delete parameters
• Lambda -- invoke self (for async operations)

All IAM policies use condition keys scoped to the specific stack's resources wherever AWS supports them, preventing cross-stack or cross-account access.

Encryption

Data	Encryption
Dashboard access	TLS 1.2+ (self-signed certificate; bring your own CA cert for production)
API communication	TLS 1.2+ (same as dashboard)
Configuration (SSM)	Encrypted at rest via AWS SSM SecureString with AWS-managed KMS key
SSH private key	Stored in SSM SecureString, encrypted at rest with AWS KMS
Proxy passwords	bcrypt-hashed before storage in SSM (never stored in plaintext)
EBS volumes	Encrypted at rest using AWS-managed EBS encryption
Inter-instance traffic	AWS VPC encryption in transit (automatic within the same region)

Network Security

The CloudFormation stack creates security groups with the following rules:

Gateway Security Group

Direction	Port	Source/Dest	Purpose
Inbound	22	clientCidrBlock	SSH access
Inbound	9443	clientCidrBlock	Dashboard and API access
Inbound	All traffic	VPC CIDR	NAT, proxy, and load balancing from private subnets
Outbound	All traffic	0.0.0.0/0	Internet access for NATed traffic

API Reference

All endpoints are available at https://<EIP>:9443/api/. Authentication is via JWT token obtained from the login endpoint.

Authentication

# Login
curl -sk https://<EIP>:9443/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin","password":"yourpass"}'
# Returns: {"token":"eyJ..."}

# Use token in subsequent requests
curl -sk -H "Authorization: Bearer eyJ..." \
  https://<EIP>:9443/api/cloudspectra/nat-gateway

Configuration Endpoints (GET/PUT)

Configuration endpoints use merge semantics on PUT -- only fields present in the request body are updated; omitted fields retain their current values.

Method	Path	Description
GET/PUT	/api/cloudspectra/nat-gateway	NAT gateway configuration
GET/PUT	/api/cloudspectra/nlb-gateway	NLB replacement (IPVS + HAProxy)
GET/PUT	/api/cloudspectra/firewall-gateway	Firewall, Suricata IDS/IPS, threat detection
GET/PUT	/api/cloudspectra/web-proxy-gateway	L7 HTTP proxy (Squid) configuration
GET/PUT	/api/cloudspectra/ai-gateway	Cloud Spectra AI Gateway configuration
GET/PUT	/api/cloudspectra/asg	Auto Scaling Group / scaling configuration
GET/PUT	/api/cloudspectra/transit-gateway	Transit manager / VPC peering mesh
GET/PUT	/api/cloudspectra/dns	DNS hosted zone and record configuration
GET/PUT	/api/cloudspectra/gateway	General gateway settings
GET/PUT	/api/cloudspectra/cloud	Cloud provider settings
GET/PUT	/api/cloudspectra/dashboard	Dashboard display preferences
GET/PUT	/api/cloudspectra/service	Service-level settings
GET/PUT	/api/cloudspectra/port-forwarding	dNAT / port forwarding rules

Operational Endpoints (Read-Only)

Method	Path	Description
GET	/api/cloudspectra/operational/capacity	Current instance capacity metrics (CPU, memory, network)
GET	/api/cloudspectra/operational/compute-capacity	Detailed compute capacity information
GET	/api/cloudspectra/operational/metadata	Instance metadata (region, AZ, instance type, AMI)
GET	/api/cloudspectra/operational/build-info	Software version and build information
GET	/api/cloudspectra/operational/instance-catalog	Available instance types with pricing and network specs
GET	/api/cloudspectra/operational/asg-metrics	ASG scaling metrics and thresholds
GET	/api/cloudspectra/operational/gwlb	GWLB status and endpoint information
GET	/api/cloudspectra/operational/snat-summary	sNAT connection table summary
GET/PUT	/api/cloudspectra/operational/log-levels	Service log level configuration

Transit Manager Endpoints

Method	Path	Description
GET	/api/cloudspectra/operational/vpcs	Discovered VPCs across all managed accounts
GET	/api/cloudspectra/operational/vpc-peering-connections	All VPC peering connections
GET	/api/cloudspectra/operational/vpc-groups	VPC groupings for selective peering
GET	/api/cloudspectra/operational/managed-accounts	Configured spoke accounts
GET	/api/cloudspectra/operational/managed-regions	Configured AWS regions
GET	/api/cloudspectra/operational/route-tables	Route table entries across managed VPCs

Account Management Endpoints

Method	Path	Description
POST	/api/cloudspectra/operational/accounts	Add a spoke account
DELETE	/api/cloudspectra/operational/accounts	Remove a spoke account
GET	/api/cloudspectra/operational/accounts/cross-account-policy	Get IAM policy for a spoke account
GET	/api/cloudspectra/operational/accounts/cross-account-stack	Get CloudFormation template for a spoke account
GET	/api/cloudspectra/operational/cross-account-iam	Cross-account IAM verification status
POST	/api/cloudspectra/operational/cross-account-iam	Verify cross-account IAM access

AZ Management Endpoints

Method	Path	Description
GET	/api/cloudspectra/operational/azs	List configured Availability Zones
POST	/api/cloudspectra/operational/azs	Add an Availability Zone
DELETE	/api/cloudspectra/operational/azs	Remove an Availability Zone
GET	/api/cloudspectra/operational/azs/status	Per-AZ health and resource status
GET	/api/cloudspectra/operational/availability-zones	Available AZs in the current region

State Endpoints (Read-Only)

Method	Path	Description
GET	/api/cloudspectra/cloud-state	Cloud provider state (VPC, subnets, IGW)
GET	/api/cloudspectra/dns-state	DNS hosted zone and record state
GET	/api/cloudspectra/gateway-state	Gateway runtime state (ASGs, ENIs, instances)
GET	/api/cloudspectra/metadata-state	Instance metadata state
GET	/api/cloudspectra/placement-state	Placement and scheduling state

Scaling Actions

Method	Path	Description
POST	/api/instance/autoscaleupdown	Trigger manual vertical scale up/down
POST	/api/cloudspectra/operational/asg-manual-scale	Manual scale direction (up or down)
POST	/api/cloudspectra/operational/gwlb	Setup or modify GWLB configuration

Terraform Provider

The Cloud Spectra Terraform provider maps each configuration section to a Terraform resource, enabling Infrastructure-as-Code management of all gateway features.

Provider Configuration

terraform {
  required_providers {
    cloudspectra = {
      source  = "cloudspectra/cloudspectra"
      version = "~> 1.0"
    }
  }
}

provider "cloudspectra" {
  gateway_url = "https://<EIP>:9443"
  password    = var.admin_password
}

Resource Examples

# NAT Gateway
resource "cloudspectra_nat_gateway" "main" {
  enable = true
}

# NLB Replacement
resource "cloudspectra_nlb_gateway" "main" {
  enable        = true
  load_balancer = "my-nlb-name"
  tls_listeners = true
}

# Firewall with threat detection
resource "cloudspectra_firewall_gateway" "main" {
  enable                               = true
  firewall_policies                    = ["production-fw-policy"]
  threat_detection_enabled             = true
  threat_detection_update_interval_hours = 24
}

# Vertical scaling
resource "cloudspectra_asg" "main" {
  mode                      = "single"
  instance_type_list        = ["c6in.large", "c6in.xlarge", "c6in.2xlarge"]
  enable_auto_scale_up_down = true
  cpu_threshold             = 70
  memory_threshold          = 85
}

# HTTP Proxy
resource "cloudspectra_web_proxy_gateway" "main" {
  enable   = true
  port     = 1080
  username = "proxyuser"
  password = var.proxy_password
}

# AI Gateway
resource "cloudspectra_ai_gateway" "main" {
  enable            = true
  port              = 8080
  default_provider  = "openai"
  cache_enabled     = true
  cache_ttl_seconds = 3600
  audit_log_enabled = true
  allowed_models    = ["gpt-4o", "claude-sonnet-4-20250514"]
}

# Transit Manager
resource "cloudspectra_transit_gateway" "main" {
  enable              = true
  peer_vpcs           = true
  managed_account_ids = ["111111111111", "222222222222"]
  managed_regions     = ["us-east-1", "us-west-2"]
}

# DNS Configuration
resource "cloudspectra_dns" "main" {
  hosted_zone_name = "gw.example.com"
  ttl              = 10
}

# Port Forwarding
resource "cloudspectra_port_forwarding" "web" {
  rules = [
    {
      enabled       = true
      protocol      = "tcp"
      external_port = 8080
      target_ip     = "10.0.1.50"
      target_port   = 80
      description   = "Web server"
    }
  ]
}

AI Assistant Beta

The Cloud Spectra AI Assistant is an in-dashboard conversational assistant powered by Amazon Bedrock (Claude). It provides real-time help with gateway status, diagnostics, configuration guidance, and direct links to relevant AWS console pages.

Enabling the AI Assistant

1. Navigate to Features > AI Gateway in the dashboard and ensure the AI Gateway feature is enabled.
2. Your AWS account must have Bedrock model access enabled for the Claude model in the same region as your Cloud Spectra deployment.
3. Once enabled, a floating chat button appears in the bottom-right corner of the dashboard. Click it to open the chat panel.

What the AI Assistant can help with

• Gateway status -- current health, instance state, ASG status, and connectivity checks
• Diagnostics -- interpreting error messages, identifying misconfigurations, and suggesting fixes
• Configuration guidance -- step-by-step help for NAT rules, firewall policies, NLB setup, and other features
• AWS console links -- direct links to relevant CloudFormation stacks, EC2 instances, and VPC resources
• Troubleshooting -- common issues like route table misconfigurations, security group rules, and IAM permission problems

Cost

Each question costs approximately $0.01, billed directly to your AWS account through Amazon Bedrock usage. There is no additional Cloud Spectra fee for the AI Assistant. Costs may vary depending on the length of the conversation and the complexity of the response.

Interface

The assistant appears as a floating button in the bottom-right corner of the dashboard. Clicking it opens a chat panel where you can type questions in natural language. The assistant streams responses in real time and supports markdown formatting for code snippets and structured output.

Troubleshooting

Stack creation fails

• Check the CloudFormation Events tab for the specific resource and error message
• Insufficient permissions -- ensure the IAM user/role creating the stack has permissions for EC2, IAM, Lambda, SSM, Route53, and CloudFormation
• AZ not available -- some instance types are not available in all AZs; try a different AZ suffix
• Instance type not supported -- verify the selected instance type is available in your region
• VPC limit reached -- default limit is 5 VPCs per region; request a limit increase or deploy into an existing VPC

Dashboard not accessible

• Verify the security group allows your IP on port 9443 (check clientCidrBlock)
• Instance may still be initializing (takes 2-3 minutes after stack creation)
• SSH to the instance and check the service: systemctl status cloudspectra_gateway_server
• Check nginx is running: systemctl status nginx
• Verify the backend is listening: curl -sk https://127.0.0.1:9443/api/auth/init-password-exists

NAT not working

• Verify route table: 0.0.0.0/0 must point to the Cloud Spectra ENI, not an AWS NAT Gateway or IGW
• Check that source/dest check is disabled on the Cloud Spectra ENI (the CloudFormation stack handles this)
• Verify the instance is running and healthy in the ASG
• Check the sNAT service: systemctl status cloudspectra_basic_features
• Verify nftables rules are present: nft list ruleset | grep masquerade

Firewall rules not syncing

• Verify firewallPolicies parameter matches the exact AWS Network Firewall policy names (case-sensitive)
• Check the sync service: systemctl status cloudspectra_firewall_sync
• View sync logs: journalctl -u cloudspectra_firewall_sync -f
• Validate Suricata rules: suricata -T -c /etc/suricata/suricata.yaml
• Verify IAM permissions allow network-firewall:DescribeFirewallPolicy and network-firewall:DescribeRuleGroup

NLB sync not working

• Verify the NLB name matches exactly (not the ARN)
• Check the sync service: systemctl status cloudspectra_network_load_balancer
• View IPVS rules: ipvsadm -Ln
• Verify IAM permissions allow elasticloadbalancing:Describe*

Transit Manager not discovering VPCs

• Verify cross-account IAM roles are deployed in each spoke account
• Check the transit service: systemctl status cloudspectra_transit_manager
• Use the dashboard to verify cross-account access: Accounts -- Verify
• Ensure the instance has 4+ vCPUs (transit manager requires c6in.xlarge or larger)

AI Gateway not starting

• The AI Gateway requires 4+ vCPUs -- verify your instance type has at least 4 vCPUs
• Check the service: systemctl status cloudspectra_ai_gateway
• View logs: journalctl -u cloudspectra_ai_gateway -f
• Verify port 8080 is not in use: ss -tlnp | grep 8080

Vertical scaling not triggering

• Verify enableAutoScaleUpDown is true and mode is single
• Check the autoscale service: systemctl status cloudspectra_autoscale_updown
• View metrics: journalctl -u cloudspectra_autoscale_updown --since "1 hour ago"
• Verify instanceTypeList contains at least 2 instance types in ascending order

Getting SSH access

# Retrieve SSH key from SSM (path from stack output SshPrivateKeyPath)
aws ssm get-parameter \
  --name /ec2/keypair/<key-id> \
  --with-decryption \
  --query Parameter.Value \
  --output text > ~/.ssh/cloudspectra-key.pem
chmod 400 ~/.ssh/cloudspectra-key.pem
ssh -i ~/.ssh/cloudspectra-key.pem admin@<EIP>

Warm pool instance not starting

• Verify warm pool is enabled: warmPoolDisabled=false in CloudFormation parameters
• Check the warm pool lifecycle service: systemctl status cloudspectra_warm_pool_watcher
• View ASG activity in the EC2 console for lifecycle hook timeout errors
• Ensure the instance type is available in the AZ (capacity constraints can prevent warm pool launches)

Frequently Asked Questions

Deployment

Q: Which AWS regions are supported?

Cloud Spectra Gateway supports all commercial AWS regions where the required services (EC2, Lambda, SSM, Route53) are available. This includes all standard regions in North America, Europe, Asia Pacific, South America, and the Middle East.

Q: Can I deploy Cloud Spectra into an existing VPC with existing workloads?

Yes. Set newOrExistingVpc=selectExisting and provide your VPC ID. Cloud Spectra creates its own /28 subnets within your VPC. Your existing subnets and workloads are not modified. You only need to update your private subnet route tables to point 0.0.0.0/0 at the Cloud Spectra ENI.

Q: How many Availability Zones can I deploy across?

Up to 6 Availability Zones per deployment. Each AZ gets its own subnet, ENI, and ASG. You can add or remove AZs at any time without downtime to existing AZs.

Q: Can I deploy multiple Cloud Spectra stacks in the same VPC?

Yes, but each stack must use different AZ configurations to avoid subnet conflicts. This is an advanced configuration typically used for separating workload classes (e.g., production vs. development).

Q: What happens during a CloudFormation stack update?

Most parameter changes (instance type, AZ additions) are applied without disrupting existing traffic. The CloudFormation Lambda handler manages the update lifecycle. Instance replacements use rolling updates through the ASG.

Features

Q: Can I use Cloud Spectra just for NAT without the other features?

Yes. NAT is the default feature and is included in the base NAT tier. All other features (firewall, proxy, NLB, transit) are optional and can be enabled as needed. You only pay for the instance running costs.

Q: How does Cloud Spectra compare to AWS NAT Gateway in performance?

Cloud Spectra NAT uses kernel-level nftables masquerade rules, which provide near-wire-speed performance. A c6in.large instance (2 vCPU) handles up to 5 Gbps. For higher throughput, scale vertically to c6in.4xlarge (50 Gbps) or use horizontal scaling with GWLB.

Q: Does the NLB replacement support health checks?

Yes. Cloud Spectra reads health check configuration from the AWS NLB target groups and only routes traffic to healthy backends. Health check results are synced every 10 seconds.

Q: Can I use TLS termination without an NLB?

TLS termination is tied to the NLB sync feature -- it reads TLS listener and certificate configurations from the NLB. You need at least a minimal NLB configured in AWS as a configuration source, even if it carries no traffic.

Q: Does the HTTP proxy support HTTPS inspection (SSL bumping)?

The HTTP proxy supports HTTPS tunneling via the CONNECT method (TLS passthrough). HTTPS content inspection (SSL bumping) is not currently enabled in v1.

Q: What LLM providers does the AI Gateway support?

The AI Gateway supports OpenAI, Anthropic, and AWS Bedrock. Provider routing is automatic based on the model name in the request. For Bedrock, the gateway signs requests using the instance's IAM role via SigV4.

Security

Q: What firewall rule formats are supported?

Cloud Spectra supports all AWS Network Firewall rule group types: Suricata-compatible stateful rules, domain list rules (HTTP_HOST + TLS_SNI), and 5-tuple stateless rules. You manage rules in the AWS console and Cloud Spectra enforces them.

Q: Are firewall rules applied during failover?

Yes. All instances share the same firewall configuration via SSM Parameter Store. When a replacement instance starts, it syncs firewall rules within 60 seconds. If ET Open threat detection is enabled, rules are pre-cached in the AMI for instant coverage.

Q: How is the dashboard password stored?

The admin password is stored in AWS SSM Parameter Store as a SecureString, encrypted at rest with AWS KMS. It is never stored on the instance's local filesystem.

Q: Can I restrict dashboard access to specific IP ranges?

Yes. Set the clientCidrBlock CloudFormation parameter to your organization's IP range (e.g., 203.0.113.0/24). This controls the security group rule for ports 22 (SSH) and 9443 (dashboard).

Q: Does Cloud Spectra support VPC Flow Logs?

Cloud Spectra does not interfere with VPC Flow Logs. You can enable VPC Flow Logs independently on your VPC, and they will capture traffic flowing through the Cloud Spectra ENIs as expected.

Scaling & High Availability

Q: What happens when a gateway instance fails?

The ASG detects the failed instance and launches a replacement. With warm pool enabled, the replacement starts in approximately 25 seconds. Without warm pool, a cold launch takes 3-5 minutes. During the replacement, the ENI maintains its private IP, so route table entries remain valid.

Q: Can I mix Spot and On-Demand instances?

Yes, in horizontal scaling mode (mode=multi). Configure a mixed instance policy with at least 1 On-Demand base instance for guaranteed availability, and use Spot instances for additional capacity.

Q: What is the maximum throughput of a single Cloud Spectra instance?

Throughput depends on the instance type. The c6in family provides high network bandwidth: c6in.large (5 Gbps), c6in.xlarge (12.5 Gbps), c6in.2xlarge (25 Gbps), c6in.4xlarge (50 Gbps), c6in.8xlarge (100 Gbps). For higher throughput, use horizontal scaling with GWLB.

Q: Does vertical scaling cause downtime?

Vertical scaling is designed for zero downtime. The ASG launches a new instance of the target type, waits for it to become healthy, then terminates the old instance. The ENI (and its IP) is reassigned to the new instance. With warm pool, this takes approximately 25 seconds.

Pricing & Cost

Q: What are the cost components of running Cloud Spectra Gateway?

The primary costs are: (1) EC2 instance hours, (2) Elastic IP charges for any EIP not associated with a running instance, (3) EBS storage for warm pool instances, and (4) minimal costs for SSM Parameter Store, Route53 hosted zones, and CloudWatch. There are no per-GB data processing fees.

Q: How much can I save compared to AWS managed services?

Savings depend on traffic volume: for NAT, you save $0.045/GB compared to AWS NAT Gateway. For NLB, you save the hourly NLB fee plus LCU charges. For transit, you save $0.05/hr per TGW attachment plus $0.02/GB. For firewall, you save $0.395/hr per AZ in endpoint costs. A typical multi-AZ deployment processing 5 TB/month can save $1,000-$3,000/month compared to equivalent AWS managed services.

Q: Is there a free tier or trial?

Cloud Spectra Gateway runs on your own AWS account. You pay standard EC2 pricing for the instances. Contact Sales@cloudspectra.ai for trial licensing and enterprise pricing.

Operations

Q: How do I upgrade Cloud Spectra Gateway software?

Software upgrades are handled automatically via the auto-upgrade mechanism on instance boot. When a new version is available, instances download and install it during their next boot cycle. You can trigger a rolling upgrade by terminating instances one at a time (the ASG launches replacements that pick up the new version).

Q: Can I SSH into Cloud Spectra instances?

Yes. The SSH private key is stored in SSM Parameter Store. Retrieve it using the AWS CLI (see the SshPrivateKeyPath stack output for the exact parameter name). Connect as the admin user.

Q: How do I monitor Cloud Spectra Gateway?

Use the dashboard Overview page for real-time metrics. CloudWatch custom metrics are published under the CloudSpectra/Gateway namespace for long-term monitoring and alerting. All services log structured JSON to journald, which can be forwarded to CloudWatch Logs, Datadog, or your preferred log aggregator.

Q: How do I back up the configuration?

All configuration is stored in SSM Parameter Store. Use aws ssm get-parameters-by-path to export the configuration, or use the Terraform provider to manage configuration as code. The API GET endpoints can also be used to export current configuration.

Q: What is the master instance?

The master instance is the gateway instance with the lowest ordinal across all AZs. It runs control-plane services that should only have a single active instance: EIP manager, DNS publisher, and transit manager. If the master fails, another instance assumes the master role automatically.