Cloud Spectra Gateway -- User Guide v1.0.0

Introduction & how configuration works

Cloud Spectra Gateway runs entirely inside your own AWS account. It is a software networking and AI appliance that replaces metered Amazon VPC networking services and metered LLM-API spend with a fixed EC2 cost -- Your Cloud, Off the Meter. There is no vendor control plane: traffic, configuration, logs and (for local inference) prompt data stay in your account at all times.

This page is the full v1 configuration reference. It is organized into the three product tiers. The tiers are cumulative -- each higher tier is a strict superset of the one below it:

Three ways to configure -- one source of truth

Every feature on this page is set the same way regardless of which interface you use. The dashboard, the Terraform provider, and the configuration API all write into the same place: AWS SSM Parameter Store, in your account. The gateway instances poll that configuration and reconcile the running data plane toward it.

flowchart LR
    DASH["Dashboard
(HTTPS 443)"]
    API["Config API
(REST 8080)"]
    TF["Terraform provider
cloudspectra/cloudspectra"]
    SSM["AWS SSM
Parameter Store
(your account)"]
    DP["Gateway data plane
(per-AZ ASG instances)"]
    DASH --> SSM
    API --> SSM
    TF --> API
    SSM -->|"poll & reconcile"| DP

Network Gateway tier Network

The Network Gateway tier is the base appliance. It delivers seven data-plane features that replace AWS-metered networking services with a fixed EC2 cost. The diagram below shows the common packet paths these features sit on -- outbound NAT, inbound port forwarding, the in-appliance L4 load balancer, and the forward proxy.

flowchart LR
    subgraph VPC["Your VPC"]
      PRIV["Private instances"]
    end
    GW["Cloud Spectra Gateway
(per-AZ ASG behind GWLB)"]
    EIP["Elastic IP
(stable endpoint)"]
    INET["Internet"]
    PRIV -->|"0.0.0.0/0 route"| GW
    GW -->|"sNAT"| EIP --> INET
    INET -->|"dNAT / port fwd"| EIP --> GW --> PRIV
    GW -->|"forward proxy (Squid)"| INET
    GW -->|"IPVS L4 load balance"| PRIV

Source NAT (sNAT)

What it does. Provides outbound internet access for instances in private subnets. The gateway source-translates private traffic to its Elastic IP so private instances can reach the internet without a public IP of their own.

Replaces. The AWS NAT Gateway -- specifically its hourly charge and its per-GB data-processing meter. With Cloud Spectra, outbound egress carries no per-GB networking fee beyond standard EC2 data-transfer.

Configure. In the dashboard, open NAT Gateway and enable outbound NAT. Then point each private subnet's route table at the gateway ENI for that Availability Zone (default route 0.0.0.0/0). The same setting is available through the Terraform provider (cloudspectra_nat_gateway) and the configuration API (PUT /api/cloudspectra/nat-gateway).

Verify. From a private instance routed through the gateway:

curl -s https://checkip.amazonaws.com
# Returns the gateway's Elastic IP -- confirms egress is source-NATed.

Destination NAT / port forwarding (dNAT)

What it does. Forwards inbound TCP connections that arrive at the gateway's public endpoint to a private target inside the VPC. Use it to expose a service running on a private instance without giving that instance a public address.

Replaces / uses. A common pattern that would otherwise require a public-facing load balancer or a bastion. dNAT pairs naturally with the gateway's Elastic IP as the stable inbound endpoint.

Configure. In the dashboard, open Port Forwarding and add a rule mapping a listen port on the gateway to a private destination IP and port. The same setting is available through the Terraform provider and the configuration API.

Verify. From outside the VPC, connect to the gateway's Elastic IP on the listen port and confirm you reach the private service:

curl -s http://<GATEWAY_EIP>:<listen_port>/
# Reaches the forwarded private target.

Network Load Balancer (IPVS L4)

What it does. Provides Layer-4 load balancing inside the appliance using the Linux IPVS engine. The gateway distributes incoming TCP/UDP flows across a set of backend targets, and keeps the IPVS target set in sync with an AWS Network Load Balancer target group so you manage targets the AWS-native way.

Replaces. The metered per-LCU/NLCU cost of an AWS Network Load Balancer for L4 traffic, while still using the AWS NLB target set as the source of truth for membership.

Configure. In the dashboard, open Load Balancer, enable the IPVS L4 balancer, and select the AWS NLB target set to mirror. The same setting is available through the Terraform provider (cloudspectra_nlb_gateway) and the configuration API.

flowchart LR
    CL["Client"] --> GW["Gateway
IPVS L4 virtual service"]
    AWSNLB["AWS NLB target group
(source of truth)"] -. "sync targets" .-> GW
    GW --> T1["Target 1"]
    GW --> T2["Target 2"]
    GW --> T3["Target 3"]

Verify. Send repeated L4 connections to the virtual service and confirm they spread across the backend targets (for example, by checking which target served each request in your application logs), and confirm the IPVS target list matches the AWS NLB target group membership.

TLS termination (ACM)

What it does. Terminates HTTPS at the gateway using HAProxy, presenting a certificate issued by AWS Certificate Manager (ACM). Inbound TLS on port 443 is decrypted at the appliance; plaintext on port 80 is redirected to HTTPS.

Uses. An ACM certificate from your account. The same HAProxy listener also fronts the management dashboard on 443.

Configure. In the dashboard, open TLS Termination and select the ACM certificate to present. The same setting is available through the Terraform provider and the configuration API.

Verify. Inspect the served certificate and confirm the redirect:

# Confirm the ACM certificate is presented on 443
openssl s_client -connect <GATEWAY_EIP>:443 -servername your.domain </dev/null 2>/dev/null | openssl x509 -noout -issuer -subject

# Confirm HTTP redirects to HTTPS
curl -sI http://<GATEWAY_EIP>/  # 301/302 to https://

Per-AZ Auto Scaling

What it does. Runs one Auto Scaling Group per Availability Zone. Each AZ's instances egress through that AZ's own ENI, so traffic stays within its zone. This is the design that keeps a gateway healthy in every AZ while avoiding cross-AZ data-transfer charges.

Replaces / uses. Uses EC2 Auto Scaling. The per-AZ split avoids the cross-AZ data-transfer cost a single shared appliance would incur when instances in one AZ NAT through an ENI in another.

Configure. Availability Zones are chosen at deployment (the CloudFormation template or the Terraform module). For each enabled AZ the stack creates a dedicated subnet, ENI, route table, and Auto Scaling Group. Point each AZ's private subnets at that AZ's gateway ENI. The same routing is settable through the Terraform provider and the configuration API.

flowchart TD
    subgraph AZa["AZ a"]
      ASGa["ASG a"] --> ENIa["ENI a"]
    end
    subgraph AZb["AZ b"]
      ASGb["ASG b"] --> ENIb["ENI b"]
    end
    subgraph AZc["AZ c"]
      ASGc["ASG c"] --> ENIc["ENI c"]
    end
    PA["Private subnets in AZ a"] --> ENIa
    PB["Private subnets in AZ b"] --> ENIb
    PC["Private subnets in AZ c"] --> ENIc

Verify. Confirm that each enabled AZ has a running gateway instance and its own ENI, and that each private subnet's route table targets the ENI in its own AZ.

Vertical & horizontal scaling (GWLB)

What it does. Scales the gateway two ways. Vertically, you can change the EC2 instance size. Horizontally, the fleet scales out behind a Gateway Load Balancer (GWLB) using GENEVE encapsulation, so multiple instances share the data-plane load. GWLB connection draining lets active flows finish before an instance is removed.

Replaces / uses. Uses a Gateway Load Balancer for horizontal scale-out and a range of EC2 instance types for vertical sizing. This removes the single-box ceiling (one NIC, fixed cores) of a fixed virtual appliance.

Configure. In the dashboard, open Scaling to change instance type (vertical) and the desired/min/max instance counts per AZ (horizontal). The same settings are available through the Terraform provider and the configuration API.

flowchart LR
    SRC["Traffic"] --> GWLB["Gateway Load Balancer
(GENEVE)"]
    GWLB --> I1["Gateway instance 1"]
    GWLB --> I2["Gateway instance 2"]
    GWLB --> I3["Gateway instance N"]

Verify. Increase the desired count and confirm new instances register healthy behind the GWLB target group and begin taking traffic; reduce the count and confirm draining lets active flows complete before an instance is removed.

Forward HTTP proxy + caching (Squid)

What it does. Runs an outbound forward proxy based on Squid. It supports proxy authentication, HTTP response caching, domain filtering, and per-client bandwidth limits -- giving you a single controlled egress point for HTTP/HTTPS traffic.

Replaces / uses. A standalone forward-proxy deployment. Caching reduces repeated outbound fetches (and therefore egress), and the filtering/bandwidth controls give you policy at the egress edge.

Configure. In the dashboard, open Forward Proxy, enable the proxy on a configurable port, and set authentication, caching, domain rules, and bandwidth limits. The same settings are available through the Terraform provider (cloudspectra_web_proxy_gateway) and the configuration API.

Verify. Configure a client to use the proxy and confirm egress flows through it:

export https_proxy=http://proxyuser:PASSWORD@<GATEWAY_IP>:<proxy_port>
curl -s https://checkip.amazonaws.com   # Returns the gateway EIP
# Repeat a cacheable request and confirm a cache HIT in the proxy access log.

Security Gateway tier Security

The Security Gateway tier includes everything in the Network tier and adds three inline enforcement features. Together they let you inspect, allow, and deny traffic at the data plane. The diagram shows where each one sits in the packet path.

flowchart LR
    IN["Inbound / outbound packet"] --> NFT["nftables
stateless allow/deny"]
    NFT -->|"allowed"| NFQ["NFQUEUE -> Suricata
IDS/IPS inline"]
    NFT -.->|"denied"| DROP1["Drop"]
    NFQ -->|"pass"| DOM["Domain / URL filter
(firewall + Squid paths)"]
    NFQ -.->|"alert / block"| DROP2["Drop / log"]
    DOM -->|"allowed"| FWD["Forward / NAT"]
    DOM -.->|"blocked domain"| DROP3["Drop"]

Suricata IDS/IPS (inline)

What it does. Runs Suricata as an inline intrusion detection and prevention system. Packets are handed to Suricata via the Linux NFQUEUE mechanism, so Suricata can inspect them and enforce a deny or allow verdict at the data plane (not just alert).

Replaces / uses. An inline IDS/IPS layer, enforced in your account on the gateway instances. No separate inspection endpoints are required.

Configure. In the dashboard, open IDS/IPS, enable inline inspection, and choose the action mode (detect vs. prevent) and rule sets. The same settings are available through the Terraform provider and the configuration API.

Verify. Generate a benign test signature match from a routed instance and confirm it appears in the Suricata events/threat view in the dashboard; in prevent mode, confirm the matching traffic is dropped.

nftables firewall rules

What it does. Enforces stateless allow/deny rules in the Linux kernel with nftables. Rules match on source and destination CIDR, port, and protocol, and are applied at the data plane on every gateway instance.

Replaces / uses. A kernel-level packet filter on the gateway. It complements the inline Suricata layer: nftables makes fast stateless allow/deny decisions; Suricata performs deep inline inspection on the traffic nftables permits.

Configure. In the dashboard, open Firewall and add rules. The same settings are available through the Terraform provider (cloudspectra_firewall_gateway) and the configuration API.

Verify. Add a deny rule for a known destination/port from a routed test instance and confirm the connection is blocked; remove it and confirm the connection succeeds again.

Domain / URL filtering

What it does. Blocks or allows traffic by domain. The policy is enforced on both data paths: the firewall path and the Squid forward-proxy path. This gives you consistent domain policy whether a client routes through NAT or through the proxy.

Replaces / uses. Domain-based egress control. Enforced in-account, on the same gateway instances.

Configure. In the dashboard, open Domain Filtering, choose an allow-list or deny-list model, and add domains. The same settings are available through the Terraform provider and the configuration API.

Verify. Add a domain to the deny-list and confirm it is blocked from a routed instance and also blocked when going through the proxy; confirm a non-listed domain still resolves and connects.

AI Gateway tier AI Gateway

The AI Gateway tier includes everything in the Security tier and adds an in-account AI data plane. It exposes an OpenAI-compatible endpoint on port 8090, can serve models locally on GPUs in your account, and caches responses to cut cost and latency. The diagram traces a request from a client through the gateway: a cache check first, then a route either to a remote provider (Amazon Bedrock, OpenAI, Anthropic) or to a local vLLM model, with a configurable fallback.

flowchart LR
    CLIENT["Client app
OpenAI base URL -> :8090"] --> EXACT{"Exact-match
cache hit?"}
    EXACT -->|"yes"| RESP["Cached response"]
    EXACT -->|"no"| SEM{"Semantic
cache hit?"}
    SEM -->|"yes"| RESP
    SEM -->|"no"| ROUTE{"Route by model"}
    ROUTE -->|"bedrock/openai/anthropic"| REMOTE["Remote provider"]
    ROUTE -->|"local/<model>"| VLLM["Local vLLM
(in-account GPU)"]
    VLLM -.->|"pre-first-token failure
+ overflow policy"| FB["Fallback remote model"]
    REMOTE --> METER["Token metering
+ audit log"] --> RESP
    VLLM --> METER
    FB --> METER

AI LLM Proxy with response caching

What it does. An OpenAI-compatible reverse proxy for LLM API calls. It fronts Amazon Bedrock, OpenAI, and Anthropic behind a single endpoint, with exact-match response caching, token metering, and audit logging. Clients keep using their existing OpenAI client libraries -- they just point the base URL at the gateway on port 8090.

Replaces / uses. A centralized LLM egress point. Exact-match caching returns identical prior responses without re-billing the provider; token metering and audit logging give you per-call accounting in your own account.

Configure. In the dashboard, open AI Gateway, enable the proxy, and configure providers, caching, metering, and audit logging. The same settings are available through the Terraform provider (cloudspectra_ai_gateway) and the configuration API.

OpenAI-compatible usage. Point your OpenAI client at the gateway's base URL on port 8090 and call the standard OpenAI API routes:

# Set the base URL to the gateway on port 8090
export OPENAI_BASE_URL=http://<GATEWAY_IP>:8090/v1

# Standard /v1/chat/completions request through the gateway
curl -s http://<GATEWAY_IP>:8090/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello, world"}]
  }'

# Route to a Bedrock or Anthropic model just by changing the model name:
curl -s http://<GATEWAY_IP>:8090/v1/chat/completions \
  -H "Authorization: Bearer $PROVIDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-3-5-sonnet",
    "messages": [{"role": "user", "content": "Hello, world"}]
  }'

Verify. Send the same chat-completion request twice and confirm the second is served from cache (lower latency, no second provider charge), and confirm the call appears in the audit log with token counts.

Local AI Inference (vLLM)

What it does. Serves LLMs locally on GPU instances in your own account using vLLM, exposed through the same OpenAI-compatible endpoint. Local models are addressed with the local/<model> prefix in the model field. On a pre-first-token failure, the gateway can fall back to a configured remote model according to an overflow policy.

Replaces / uses. In-account GPU serving with vLLM. The fallback can target a remote provider (Bedrock / OpenAI / Anthropic) when local capacity is unavailable.

Overflow policy. The fallback behavior on a pre-first-token failure is governed by the overflow policy:

Configure. In the dashboard, open Local Inference, register a local vLLM model, and set the overflow policy and (optionally) the remote fallback model. The same settings are available through the Terraform provider and the configuration API.

# Call a local model via the OpenAI-compatible endpoint
curl -s http://<GATEWAY_IP>:8090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local/llama-3.1-8b-instruct",
    "messages": [{"role": "user", "content": "Summarize this internal doc."}]
  }'

Verify. Send a request to a local/<model> name and confirm it is served by the local vLLM instance; then exercise the overflow policy (for example, with spill, confirm a pre-first-token failure falls back to the configured remote model; with an empty fallback, confirm the request is queued or rejected and never leaves the account).

AI Semantic Cache

What it does. Adds an embedding-based cache that recognizes similar prompts, not just byte-identical ones. Where the exact-match cache only hits on an identical request, the semantic cache returns a stored response for a sufficiently similar prompt -- raising the overall cache hit rate.

Replaces / uses. Extends the response caching of the AI LLM proxy. Higher hit rates mean fewer billed provider calls and lower latency for near-duplicate prompts.

Configure. In the dashboard, open AI Gateway -- Semantic Cache and enable it. The same setting is available through the Terraform provider and the configuration API.

Verify. Send a prompt, then send a slightly reworded but semantically equivalent prompt, and confirm the second is served from the semantic cache (lower latency, no new provider charge).

Ports & endpoints reference

The gateway exposes the following ports. Restrict access to each to the smallest client CIDR that needs it.

Cross-account / home-account IAM role

The base CloudFormation template (new-VPC or existing/BYO-VPC) ships an intentionally minimal instance role. From it the gateway boots, elects a leader, associates its Elastic IP, and runs outbound source NAT on its primary interface -- with no further configuration. Most other features, however, require a separately deployed operational IAM role -- the cross-account / home-account role -- without which those features will not work.

You deploy this operational role once in your home account (the account running the gateway) and once in each additional account you want the gateway to manage. The gateway computes every IAM policy for you; you never hand-edit policy JSON.

What the operational role unlocks

Each capability below maps to one operational function role named <name>-cross-account-roleN. When the matching role is absent -- the stack is not deployed, or you deselected the feature -- that capability is simply inert: the gateway keeps running and retries; it does not crash.

Naming and trust

The operational roles are named <name>-cross-account-roleN, where <name> is derived from your resource-name prefix (default cloudspectra), the manager stack name, and the manager stack ID. The gateway rebuilds these names at runtime in order to assume the roles, so the deployed names must match exactly. Each role trusts only two principals in your home account -- the gateway instance role (<name>-instance) and the CloudFormation handler role (<name>-cf-handler-role) -- gated by an external ID, and optionally by your AWS Organizations ID. Each role's permissions are inline and fully visible to your security team for review.

Setting it up

From the dashboard's Setup IAM Roles view, each account row offers three ways to deploy the operational role. The gateway pre-fills every IAM policy, so you never type permissions.

After the stack reaches CREATE_COMPLETE (or the CLI finishes), use the dashboard's Add Account action to register the account so the gateway begins managing it.

Updating it over time

As Cloud Spectra ships features that need new permissions, the operational role is updated through CloudFormation -- the gateway never edits your IAM at runtime. The template itself is frozen -- only its parameter values change between releases, so an update never disturbs the roles you have already deployed.

After your gateway auto-upgrades, it regenerates the policies and -- on the dashboard's account view -- stages a CloudFormation Change Set on your existing stack against the new release. You open the link, review the diff in the CloudFormation console, and click Execute. (For an account that has no stack yet, the dashboard gives you a Quick-Create URL instead.) The cloudspectra-setup CLI is the alternative: re-run it with a fresh token to apply the update.

flowchart TD
    BASE["Base CloudFormation template
(minimal instance role)"] --> BOOT["Boot, leader election,
master EIP, primary-interface NAT"]
    DASH["Gateway dashboard"] -->|"Quick-Create URL /
Change Set / CLI / IaC"| OPS["Operational role stack
(cross-account / home-account)"]
    OPS --> FEAT["Most features:
full NAT data plane, GWLB, DNS,
flow logs, scaling, AI Gateway"]
    DASH -->|"new release:
stage Change Set"| UPD["Review diff in console,
click Execute"]
    UPD --> OPS
    TRUST["Trust: instance role +
cf-handler role, external ID"] --> OPS
    style BASE fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
    style BOOT fill:#d1fae5,stroke:#10b981,color:#065f46
    style OPS fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style FEAT fill:#d1fae5,stroke:#10b981,color:#065f46
    style DASH fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style UPD fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style TRUST fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a

Deployment & upgrades

There are three supported ways to deploy Cloud Spectra Gateway. All three deploy into your own AWS account and produce the same runtime: a per-AZ Auto Scaling Group behind a Gateway Load Balancer, with an Elastic IP as a stable endpoint and configuration in SSM Parameter Store.

flowchart TD
    MP["AWS Marketplace
1-click subscribe"] --> CF["CloudFormation"]
    CF --> NEWVPC["New-VPC template"]
    CF --> EXVPC["Existing / BYO-VPC template"]
    TFM["Terraform
(network mirror provider)"] --> RUNTIME["Per-AZ ASG behind GWLB
+ EIP + SSM config"]
    AMI["Standalone AMI
(no CloudFormation)"] --> RUNTIME
    NEWVPC --> RUNTIME
    EXVPC --> RUNTIME

CloudFormation (new VPC or existing/BYO VPC)

From the AWS Marketplace listing, 1-click launches a CloudFormation stack. Two base templates are provided:

See the Quick Start for the step-by-step CloudFormation walkthrough.

Terraform (via a one-time network mirror)

Deploy and configure with Terraform using the cloudspectra/cloudspectra provider plus AWS modules. The provider is installed from a network mirror -- add a one-time network_mirror block to your ~/.terraformrc so Terraform can fetch it:

# ~/.terraformrc  (one-time)
provider_installation {
  network_mirror {
    url = "https://<cloudspectra-network-mirror>/"
  }
  direct {
    exclude = ["cloudspectra/cloudspectra"]
  }
}

terraform {
  required_providers {
    aws          = { source = "hashicorp/aws", version = ">= 5.0" }
    cloudspectra = { source = "cloudspectra/cloudspectra" }
  }
}

provider "cloudspectra" {
  gateway_url    = "https://<GATEWAY_EIP>"
  admin_password = var.cloudspectra_admin_password
}

# Every feature on this page maps to a provider resource, e.g.:
resource "cloudspectra_nat_gateway"        "main" { enable = true }
resource "cloudspectra_firewall_gateway"   "main" { enable = true }
resource "cloudspectra_web_proxy_gateway"  "main" { enable = true }
resource "cloudspectra_ai_gateway"         "main" { enable = true }

Standalone AMI (no CloudFormation)

You can launch the AMI directly into a subnet. It boots with outbound NAT and the management dashboard already running -- no CloudFormation stack required. This is the lightest-weight way to evaluate the gateway or to run it in environments where you manage the surrounding infrastructure yourself.

Upgrades

Because the runtime is a per-AZ Auto Scaling Group, upgrades roll through the fleet instance by instance. Gateway Load Balancer connection draining lets active flows on an instance finish before it is replaced, so planned upgrades and resizes are seamless. Configuration in SSM Parameter Store is preserved across instance replacement, so the data plane reconciles back to your declared state automatically.