Gateway Mode

The Aegis Gateway is the deployment unit you put in front of your services to enforce crypto-agile policy, terminate (or transparently gate) TLS, and meter encrypted traffic for billing.

This guide covers the lifecycle: install → enroll → policy → rollout → rotate.

Quick start (Docker Compose)

The fastest end-to-end demo. Five minutes from git clone to bytes flowing through a real gateway.

git clone https://github.com/velikey/aegis.git
cd aegis
./scripts/demo/gateway-compose.sh

What you get:

Service	Purpose
`httpbin`	Upstream HTTP backend
`aegis-gateway`	Standalone gateway bin (this crate's `[[bin]]`)
`traffic-driver`	`curl` loop generating allow + deny attempts

The script asserts at least one gateway.handshake established log event AND one gateway.proxy session closed event before passing. See aegis/scripts/demo/README.md for full reference.

Production install (Kubernetes)

Two pre-reqs (one-time per cluster):

# Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml

# cert-manager
helm install cert-manager jetstack/cert-manager \
  --create-namespace --namespace cert-manager --set installCRDs=true

Then install the chart with the production values file:

helm install aegis oci://ghcr.io/velikey/charts/aegis \
  --version 0.2.0 \
  -f charts/aegis/examples/gateway-mode-values.yaml

The chart provisions:

aegis-control-plane (the orchestration plane).
aegis-controller (Kubernetes controller for GatewayClass / Gateway / HTTPRoute resources).
aegis-agent (DaemonSet on every node — sees host-local traffic for the transparent egress gate).
(Optional) Example Gateway + HTTPRoute resources you can take as a starting point.

Once installed, every Gateway resource that selects the aegis GatewayClass is reconciled by the controller — provisioning a Service + Deployment of aegis-gateway pods, owner-referenced to the Gateway so kube garbage-collects them on Gateway delete.

Operator-friendly install (CLI / dashboard)

If your team operates outside Kubernetes (bare-metal, EC2, ECS), use the install plan flow:

From the dashboard

Sign in to https://axis.velikey.com.
Sidebar → Gateways → New Gateway.
Fill out: name, mode (ingress / egress / both), compliance template (SOC 2 / PCI / HIPAA / GDPR / Custom), backend URL.
Click Mint install plan.
Copy the install script onto your host within 15 minutes (the bootstrap token expires).

From the CLI

aegis gateway init \
  --name edge-prod \
  --mode ingress \
  --template soc2 \
  --backend-url https://api.svc.cluster.local:8443

Output is the same install script the dashboard renders. Run it on the target host:

sudo bash install.sh

From an SDK

JavaScript:

import { VeliKeySDK } from "@velikey/sdk";

const sdk = new VeliKeySDK({ apiKey: process.env.VELIKEY_API_KEY });
const plan = await sdk.gateways.installPlan({
  name: "edge-prod",
  mode: "INGRESS",
  template: "SOC2",
  backendUrl: "https://api.svc.cluster.local:8443",
});
console.log(plan.installScript);

Python:

from velikey import AegisClient

client = AegisClient(api_key=os.environ["VELIKEY_API_KEY"])
plan = await client.gateways.install_plan(
    name="edge-prod",
    mode="INGRESS",
    template="SOC2",
    backend_url="https://api.svc.cluster.local:8443",
)
print(plan["installScript"])

Go:

plan, err := client.Gateways.InstallPlan(ctx, velikey.InstallPlanRequest{
    Name:       "edge-prod",
    Mode:       "INGRESS",
    Template:   ptr("SOC2"),
    BackendURL: ptr("https://api.svc.cluster.local:8443"),
})

Lifecycle operations

Status

aegis gateway list
aegis gateway show gw_4f9b2c8d1e

The status is the canonical resource view: agent version, cert expiration, last rollout, current policy, last 25 audit entries (linked).

Cert / key rotation

aegis gateway rotate gw_4f9b2c8d1e --target cert --confirm ROTATE

Returns 202 Accepted with a rotationId. The reconciler picks it up on the next agent heartbeat (60s) and the new cert is loaded via the hot-reload watcher (aegis_gateway::cert_source) — no proxy restart, no in-flight connection drops.

Canary rollout

Three-step canary by default (5% → 50% → 100%):

aegis gateway canary-plan --policy-id pol_12345 --canary-percent 5
# returns plan_xyz

aegis gateway canary-apply --plan-id plan_xyz --confirm APPLY
# returns rollout_abc + rollback_token rb_def

# the engine auto-progresses through phases on healthy telemetry,
# auto-rolls back on regression. Manual rollback:
aegis gateway rollback --rollback-token rb_def --confirm ROLLBACK

Decommission

aegis gateway decommission gw_4f9b2c8d1e --confirm DECOMMISSION

The Gateway row is moved to DECOMMISSIONED status. The data-plane pods (in K8s) or systemd units (on hosts) are torn down by the controller / install script's matching uninstall path.

Compliance templates

Built-in templates for the four most-requested frameworks. Each template is a concrete starting point — exact cipher suites, audit retention, redaction rules — that the policy editor lets you customize before applying:

Template	Aligned framework	Key constraints
`soc2`	SOC 2 (AICPA TSC)	TLS 1.2 minimum, 365-day audit retention
`pci`	PCI DSS v4.0	TLS 1.3 only, AES-GCM + CHACHA20 only, PII redaction
`hipaa`	HIPAA Security Rule	TLS 1.2 minimum, 6-year audit retention, PHI redaction
`gdpr`	GDPR Art. 32	TLS 1.2 minimum, configurable PII redaction
`custom`	Tenant-defined	Empty starting point

About these templates

These are policy starting points whose technical controls are designed to support the named frameworks' objectives, and the evidence Aegis produces is intended to help with your audit. Applying a template does not make you — or VeliKey — certified or compliant, and VeliKey is not itself a SOC 2 / PCI / HIPAA audited entity. Compliance is achieved through your own program and a third-party assessor.

Templates are applied via a standard rollout (no separate apply UX). Pick a template at install time (--template soc2) or via the Compliance bundles dashboard tab.

Observability

Every gateway pod emits structured tracing spans:

Target	When	Useful fields
`gateway.handshake`	TLS handshake outcome	`connection_id`, `peer_addr`, `algorithms`, `outcome`
`gateway.proxy`	Proxy session close	`from_client`, `from_backend`, `duration_ms`
`gateway.policy_decision`	Allow / deny	`policy_id`, `rule_id`, `decision`

These are converted into CloudWatch metrics by the filters at ops/cloudwatch/gateway-log-filters.json and feed three operator alarms (handshake failure rate, cert expiring, policy deny spike) — see Monitoring & Alerts.

OTel export is opt-in via the otel build feature (cargo build --features otel) + OTEL_EXPORTER_OTLP_ENDPOINT env var. When enabled, all three Aegis services (aegis-gateway, aegis-agent, aegis-control-plane) emit traces with consistent service.name resource attributes.

Service mesh integration

Once your gateways are running, the Phase 4 mesh adapter binds Aegis policies to specific east-west services. Istio is the first-class target:

aegis mesh init istio --cluster prod-us --mode ambient
aegis mesh bind service payments.default.svc.cluster.local --policy pol_12345

See Service Mesh integration for details. Linkerd and Consul adapters ship behind feature flags (MESH_LINKERD_ADAPTER_ENABLED=true / MESH_CONSUL_ADAPTER_ENABLED=true).

Reference

Control Plane API — the Gateway resource API (CRUD, install plans, rotation). Full OpenAPI 3.1 spec ships in the repo at docs/api/gateways.openapi.yaml.
Architecture — how the gateway data path, control plane, and agents fit together.
Monitoring & Alerts — gateway SLOs (handshake success rate, p95 latency) and the operator alarms.
Engineering design records (ADR-0002 gateway runtime unification, the SLO definitions, and the implementation plan) live in the source repositories for contributors.