Control CoreDocs

🚀 Bouncer Deployment Guide

📌 Overview

Control Core Bouncers (Policy Enforcement Points) are the components that protect your resources by intercepting traffic and enforcing authorization policies. This guide walks you through deploying bouncers in your infrastructure and connecting them to the Control Plane.

📌 Active Implementation

Control Core ships a single bouncer runtime that is deployed in two modes:

  • BOUNCER_TYPE=sidecar for one bouncer per workload instance
  • BOUNCER_TYPE=reverse-proxy for shared ingress / gateway deployment

Older folders such as archived/legacy/cc-bouncer/ and archived/legacy/cc-bouncer-sidecar/ are legacy implementations retained only for historical reference and migration context.

🏗️ Architecture: One Control Plane, Multiple Bouncers

The architecture is one Control Plane and multiple bouncers. Bouncers always come in pairs (Sandbox and Production), and the resource they protect is also in pairs (sandbox resource and production resource).

  • One Control Plane: A single Control Plane manages policy, registration, and policy sync for all bouncers.
  • Multiple Bouncers: You deploy as many bouncer pairs as you have logical resources to protect (e.g. one pair per API, one pair per database gateway).
  • Bouncers in pairs: For each logical resource you deploy two bouncers—one with ENVIRONMENT=sandbox and one with ENVIRONMENT=production. They share the same RESOURCE_NAME so the Control Plane links them as a pair.
  • Resources in pairs: The Control Plane creates or links a sandbox resource and a production resource per logical resource, one per bouncer. Policies are developed in sandbox and promoted to production; each environment only sees its own policies.

Pairing is by RESOURCE_NAME: use the same RESOURCE_NAME for the sandbox and production bouncer that protect the same logical resource (e.g. "Payment API"). The Control Plane pairs bouncers and resources by that name and environment.

🏗️ Architecture

Control Core Bouncers enforce policies at the network layer. Bouncers act as intelligent proxies or sidecars that:

  • Intercept all requests to protected resources at the network layer
  • Evaluate authorization policies in real time
  • Enforce policies without application code changes
  • Report metrics and health status to Control Plane
  • Auto-discover and register resources
  • Support advanced features: circuit breakers, retries, rate limiting, service mesh integration

Generic PBAC Architecture

Control Core Bouncers are designed as generic Policy-Based Access Control (PBAC) solutions that work across many resource types, not just APIs. The active bouncer implementation is policy-driven with no hardcoded application paths or resource names.

Transport scope: The current production-ready runtime is HTTP-family based. It is ready today for REST, GraphQL, MCP/A2A over HTTP, SSE, WebSocket, and gRPC traffic. Other logical resource types such as databases, files, or queues should be fronted by an HTTP/gRPC gateway or service endpoint if you want to protect them with this bouncer.

Policy-Driven Resource Processing

  • No Hardcoded Paths: The bouncer queries policies to determine which resources to process
  • Generic Resource Types: Supports any logical resource type through policy and metadata (RESOURCE_TYPE, headers, context)
  • Content-Agnostic: Policies determine content handling (JSON, XML, binary, text, etc.)
  • Action-Aware: Supports any action type (read, write, execute, query, create, update, delete)

Supported Resource Types

Control Core Bouncers can protect directly today:

  • REST APIs: JSON/XML responses
  • GraphQL APIs: Query responses
  • Microservices: Service-to-service communication
  • WebSockets: Real-time data streams
  • gRPC: Protocol buffer responses
  • MCP / A2A endpoints: JSON-RPC and agent traffic over HTTP

Other resource domains can still be represented as RESOURCE_TYPE values in policy:

  • Databases
  • File systems
  • Message queues
  • Custom resources

Use those when the protected system is exposed through an HTTP or gRPC gateway that the bouncer can sit in front of.

Policy Decision Points

The bouncer queries policies for:

  1. Should Process: should_process_response rule determines if a resource should be processed
  2. Content Format: Policies receive content metadata (is_json, format) to handle appropriately
  3. Resource Type: Extracted from headers (x-resource-type) or context, not hardcoded
  4. Action Type: Derived from HTTP method or headers, mapped intelligently (GET→read, POST→create, etc.)
  5. Transformation Rules: Policies determine data masking, filtering, and transformation

Example: Policy-Driven Processing

package controlcore.demoapp_api.data_protection

import rego.v1

# Policy determines if this resource should be processed
default should_process_response := true

# Skip processing for public endpoints
should_process_response := false if {
  is_public_endpoint
}

# Policy handles any resource type
is_public_endpoint if {
  public_endpoints[input.resource.path]
}

# Public endpoints defined in policy (not bouncer)
public_endpoints contains "/auth/demo-users"
public_endpoints contains "/health"

Key Benefits:

  • ✅ Generic: Works with any resource type
  • ✅ Policy-Driven: All decisions come from policies
  • ✅ Extensible: Add new resource types via policy configuration
  • ✅ Production-Ready: Follows PBAC best practices
  • ✅ Backward Compatible: Existing API policies continue to work

🚀 Deployment Scenarios

Control Core Bouncers can be deployed in multiple patterns depending on your infrastructure needs:

1. Sidecar Deployment (Training/Development Pattern)

The sidecar pattern runs the bouncer as a container alongside your application container, sharing the same network namespace. This is ideal for containerized applications and microservices.

Click to enlarge

Use Cases:

  • Containerized applications (Docker, Kubernetes)
  • Microservices architectures
  • Demo App training environments
  • Service mesh integration

Configuration:

  • BOUNCER_TYPE=sidecar
  • TARGET_HOST=<app-container-name>
  • TARGET_PORT=<app-port>
  • Same Docker network as application

2. Reverse Proxy Deployment

The reverse proxy pattern places the bouncer in front of your application, acting as a gateway. All external traffic goes through the bouncer.

Click to enlarge

Use Cases:

  • Public-facing APIs
  • Web applications
  • API gateways
  • Load balancer replacement

Configuration:

  • BOUNCER_TYPE=reverse-proxy
  • TARGET_HOST=<upstream-host>
  • TARGET_PORT=<upstream-port>
  • Public port exposure

📌 Traffic Path Integrity (Prevent Bouncer Bypass)

Port-level bypass is the most common production misconfiguration: the frontend or upstream clients accidentally point to the app's direct port (for example :8000) instead of the bouncer entrypoint (for example :8080).

Source-of-truth routing chart

Deployment modeClient-visible URL must point toApp direct port exposure
SidecarBouncer listener (:8080) in the pod/service pathKeep app port internal-only (:8000), not externally routable
Reverse proxyBouncer public URL / gateway hostnameKeep upstream app on private network only

Sidecar hardening steps

  1. Set app service/ingress targetPort to bouncer port (8080), not the app port.
  2. Keep app container port (8000) reachable only from localhost/pod network.
  3. Configure frontend and server-side API base URLs to the bouncer address.
  4. Use a separate internal-only variable for bootstrap calls that must bypass policy (rare).
  5. Add a startup guard that fails deployment if API URL resolves to app direct port.

Reverse proxy hardening steps

  1. Publish only the bouncer endpoint (LB/ingress/API gateway).
  2. Keep upstream app service private (no public ingress/public NodePort).
  3. Ensure DNS points to bouncer, not upstream app.
  4. Block direct app access with security groups/network policies/firewall rules.
  5. Run synthetic checks against both routes: bouncer path must pass, direct path must be blocked.

Fast verification commands

# 1) Verify client/server API URL values resolve to bouncer endpoint
echo "$NEXT_PUBLIC_API_BASE_URL"
echo "$DEMOAPP_API_URL"

# 2) Verify bouncer path returns policy headers/status as expected
curl -i http://localhost:8080/health

# 3) Direct app path should be private/unreachable from client plane
curl -i http://localhost:8000/health

Protocol-Specific Workloads on the Same Bouncer

MCP, A2A, AI Pilot, and similar workloads do not require separate bouncer codebases. Use the same bouncer in either sidecar or reverse-proxy mode and configure the protected workload with:

  • RESOURCE_TYPE for the logical resource category
  • upstream routing (TARGET_HOST, TARGET_PORT)
  • protocol-aware policies in Control Plane
  • headers or path conventions that let policy distinguish the workload

🚀 Dual Environment Deployment (Default Architecture)

Control Core exclusively uses dual environment deployment—one Control Plane, multiple bouncers, with bouncers and resources always in pairs (Sandbox and Production). This is not optional; it is the core design.

Required: Sandbox Environment (Deploy First)

  • Where you start: All Control Core deployments begin with sandbox
  • Policy development: ALL policies are created and tested here
  • Safe experimentation: No impact on production traffic
  • API Key: Generate sandbox key (sk_test_...) in Settings > Environments
  • Required configuration: ENVIRONMENT=sandbox

Production Environment (Deploy as Pair)

  • Pair with sandbox: For each sandbox bouncer, deploy a production bouncer with the same RESOURCE_NAME and ENVIRONMENT=production
  • Policy enforcement: Production enforces promoted policies only
  • Live traffic: Protects production resources
  • API Key: Generate production key (sk_live_...) in Settings > Environments
  • Required configuration: ENVIRONMENT=production

Bouncer and Resource Pairing

Bouncers protecting the same logical resource form a pair (sandbox + production). The resource is also in a pair (sandbox resource + production resource), linked by the same RESOURCE_NAME:

One Control Plane
│
├── Resource: "Payment API" (logical)
│   ├── Sandbox Bouncer          Sandbox Resource
│   │   ├── ENVIRONMENT=sandbox  (created/linked on registration)
│   │   ├── RESOURCE_NAME="Payment API"  ← SAME NAME
│   │   └── Protects: https://test-payment-api.com
│   │
│   └── Production Bouncer      Production Resource
│       ├── ENVIRONMENT=production  (created/linked on registration)
│       ├── RESOURCE_NAME="Payment API"  ← SAME NAME
│       └── Protects: https://payment-api.com
│
├── Resource: "Customer API" (another pair)
│   ├── Sandbox Bouncer + Sandbox Resource (RESOURCE_NAME="Customer API")
│   └── Production Bouncer + Production Resource (RESOURCE_NAME="Customer API")
│
└── … more bouncer pairs as needed

Control Core automatically pairs bouncers and resources by matching RESOURCE_NAME and environment.

Registration on Deployment

When the bouncer starts, it registers itself and the resource it is protecting with the Control Plane so the Control Plane knows which bouncer protects which resource. This happens automatically on deployment when the required environment variables are set.

  • Required for registration: PAP_API_URL, API_KEY, BOUNCER_ID (set by your deployment).
  • Recommended for resource registration: RESOURCE_NAME, TARGET_HOST, TARGET_PORT, BOUNCER_NAME, ENVIRONMENT so the protected resource is created or linked correctly in the Control Plane.
  • After registration, the bouncer and its protected resource appear in Settings > Bouncers and Settings > Resources. When you create a policy or control in the Policy Builder (step 1), you link it to a Resource and Bouncer. The Policy Bridge (Policy Bridge) then syncs that policy only to the selected bouncer(s) for that resource—not to every bouncer. Policies are distributed on a configurable interval (default 30 seconds). To pull the latest policies immediately, use Sync policies (or equivalent) from Settings > Bouncers for that bouncer.

Intelligent Auto-Configuration

When you deploy a bouncer, Control Core automatically:

  • ✅ Registers the bouncer and its protected resource with the Control Plane on startup
  • ✅ Filters policies by environment (no manual configuration)
  • ✅ Routes data sources to correct endpoints (sandbox vs production)
  • ✅ Pairs bouncers by resource name
  • ✅ Optimizes cache settings per environment
  • ✅ Organizes policies in GitHub folders
  • ✅ Configures policy distribution

You just set the required variables at deployment, Control Core handles the rest!

📌 Prerequisites

Before deploying a bouncer, ensure you have:

  • Control Core Control Plane running and accessible
  • API credentials (API Key and Tenant ID)
  • Network connectivity from bouncer to Control Plane
  • One of the following deployment platforms:
    • Docker / Docker Compose
    • Kubernetes cluster with Helm
    • Linux server for binary deployment

📌 Step 1: Download Bouncer

From Control Core Admin UI

  1. Navigate to Settings > Bouncers > Download Center
  2. Select your deployment pattern:
    • Reverse Proxy Bouncer - Same bouncer deployed in front of a resource
    • Sidecar Bouncer - Same bouncer deployed beside a resource
  3. Choose deployment format (Docker Compose, Helm Chart, or Kubernetes Manifest)
  4. Select version (latest recommended)
  5. Choose environment (Sandbox or Production)
  6. Click Download

Note: Bouncers enforce policies at the network layer by default. Pick the deployment mode based on topology, then configure the resource details and policies.

Package Contents

The downloaded package includes:

  • Bouncer binary or container image
  • config.yaml - Configuration template (or use environment variables)
  • docker-compose.yml or helm-values.yaml - Deployment files
  • setup.sh - Optional one-time setup; registration is automatic when the bouncer starts with required env vars set by your deployment
  • README.md - Quick start guide
  • Environment-specific examples

📌 Step 2: Configuration

Extract the Package

# Extract the downloaded package
tar -xzf control-core-bouncer-v2.1.0-sandbox.tar.gz
cd control-core-bouncer-v2.1.0-sandbox

Configure Connection Settings

Edit the config.yaml file:

# Control Plane Connection
control_plane:
  url: "https://your-control-plane.company.com"
  api_key: "your-api-key-here"
  tenant_id: "your-tenant-id"

# Bouncer Identity
bouncer:
  id: "bouncer-sandbox-api-1"
  name: "Sandbox API Gateway Bouncer"
  type: "reverse-proxy"  # or sidecar, mcp, agent-to-agent, iot
  version: "v2.1.0"

# Environment
deployment:
  environment: "sandbox"  # or production
  platform: "docker"      # kubernetes, docker, binary
  region: "us-east-1"

# Resource Protection
resource:
  name: "Customer API"
  type: "api"  # api, webapp, database, ai-agent, mcp-server
  original_host_url: "https://api.yourcompany.com"
  target_host: "api-service:8000"  # Internal service address
  security_posture: "deny-all"     # deny-all (recommended) or allow-all

# Network Settings
network:
  listen_port: 8080
  target_url: "http://api-service:8000"  # Internal URL of the protected resource
  proxy_url: "https://bouncer-sandbox.yourcompany.com"  # Public URL where clients access the protected resource through the bouncer

# Health Check
health:
  enabled: true
  heartbeat_interval: 30  # seconds
  timeout: 10

# Logging
logging:
  level: "info"  # debug, info, warn, error
  format: "json"
  audit_enabled: true

# Cache (optional)
cache:
  enabled: true
  ttl: 300  # seconds
  max_size: 1000

# Rate Limiting (optional)
rate_limit:
  enabled: true
  requests_per_minute: 1000
  burst: 100

Environment Variables

Alternatively, configure using environment variables. Use PAP_API_URL and API_KEY; set these in your deployment (Docker, Kubernetes, sidecar) so the bouncer can register and sync policies:

# Control Plane (required for registration and policy sync)
export PAP_API_URL="https://your-control-plane.company.com/api"
export API_KEY="your-api-key-here"

# Bouncer identity (required for registration)
export BOUNCER_ID="bouncer-sandbox-api-1"
export ENVIRONMENT="sandbox"

# Resource and target (recommended for resource registration)
export BOUNCER_NAME="Sandbox API Gateway Bouncer"
export RESOURCE_NAME="Customer API"
export RESOURCE_TYPE="api"
export TARGET_HOST="api-service"
export TARGET_PORT="8000"
export BOUNCER_TYPE="reverse-proxy"   # or sidecar

# Optional: URL the Control Plane can GET to verify bouncer without waiting for heartbeat
# Use a URL reachable from the Control Plane (e.g. bouncer health /ready)
export BOUNCER_HEALTH_URL="http://bouncer:9901/ready"

# Network (as needed)
export TARGET_URL="http://api-service:8000"

Registration runs automatically when the bouncer process starts with these variables set; no separate script is required.

🚀 Step 3: Deploy the Bouncer

Docker Compose Deployment

# Review the docker-compose.yml
cat docker-compose.yml

# Start the bouncer
docker-compose up -d

# Check logs
docker-compose logs -f control-core-bouncer

Kubernetes / Helm Deployment

# Update helm values
vi helm-values.yaml

# Install the helm chart
helm install control-core-bouncer-sandbox ./helm-chart \
  --values helm-values.yaml \
  --namespace control-core \
  --create-namespace

# Check status
kubectl get pods -n control-core
kubectl logs -n control-core deployment/control-core-bouncer-sandbox -f

Binary Deployment

# Make the binary executable
chmod +x control-core-bouncer

# Run with configuration file
./control-core-bouncer --config config.yaml

# Or run with environment variables
./control-core-bouncer

Docker Run (Quick Test)

Use service/container names control-core-bouncer-sb-<resourcename> (sandbox) and control-core-bouncer-prod-<resourcename> (production), where <resourcename> is a short identifier for the resource (e.g. demoapp, customer-api). Use "bouncer" in the service name (e.g. control-core-bouncer-sb-demoapp), not other product names.

Set required ports and identity via env vars:

docker run -d \
  --name control-core-bouncer-sb-customer-api \
  -p 8080:8080 -p 9901:9901 \
  -e PAP_API_URL="https://your-control-plane.company.com/api" \
  -e API_KEY="your-api-key-here" \
  -e BOUNCER_ID="bouncer-sandbox-api-1" \
  -e ENVIRONMENT="sandbox" \
  -e RESOURCE_NAME="Customer API" \
  -e TARGET_HOST="api-service" \
  -e TARGET_PORT="8000" \
  controlcore/envoy-bouncer:v2.1.0

(The image above is the Control Core bouncer image.)

Registration runs automatically when the container starts with these variables set.

📌 Step 4: Verify Connection

Check Bouncer Logs

Look for successful registration:

INFO: Bouncer starting...
INFO: Connecting to Control Plane at https://your-control-plane.company.com
INFO: Registration successful - Bouncer ID: bouncer-sandbox-api-1
INFO: Resource auto-discovery complete - Resource: Customer API
INFO: Health check enabled - Heartbeat interval: 30s
INFO: Bouncer ready - Listening on port 8080
INFO: Status: Connected, Intercepting Traffic: true

Verify in Control Core Admin UI

  1. Navigate to Settings > Bouncers (PEP management).

  2. You should see your bouncer listed with:

    • ✅ Connected (green indicator)
    • ⚡ Intercepting Traffic badge
    • 🟢 Sandbox or 🔴 Production environment badge
    • Last seen timestamp (should be recent; heartbeats every 30s by default).

  3. Confirm connection without waiting for heartbeat: If you set BOUNCER_HEALTH_URL when deploying the bouncer, use Confirm Connection on the PEP row. The Control Plane will ping that URL and update status immediately so you can verify registration and connectivity without waiting for the next heartbeat.

  4. Check the resource was auto-discovered:

    • Navigate to Settings > Resources
    • Filter by environment (Sandbox/Production)
    • Your resource should be listed and linked to the bouncer

Test the Bouncer

Send a test request through the bouncer:

# Make a request to the bouncer
curl -X GET http://localhost:8080/api/v1/customers \
  -H "Authorization: Bearer test-token"

# Expected: 403 Forbidden (if no policies configured yet)
# Or: 200 OK (if you have an allow policy)

📌 Step 5: Configure Routing

Reverse Proxy Mode

Update DNS or load balancer to route traffic through the bouncer:

Option 1: DNS CNAME

api.yourcompany.com -> bouncer-sandbox.yourcompany.com

Option 2: Load Balancer

Update ALB/NLB target to point to bouncer

Option 3: Ingress Controller (Kubernetes)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
spec:
  rules:
  - host: api.yourcompany.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: control-core-bouncer-sandbox
            port:
              number: 8080

Sidecar Mode

The bouncer is already running alongside your service container. Update your application to route requests through localhost:

// Before
const API_BASE_URL = 'http://api-service:8000';

// After (route through bouncer sidecar)
const API_BASE_URL = 'http://localhost:8080';

🤖 Failure Semantics and Availability (Production)

For enterprise production deployments, define your failure behavior explicitly before go-live.

  • Availability principle: The protected resource should remain reachable even if one bouncer instance fails.
  • Recommended topology for uptime SLOs: Load Balancer -> HA bouncer fleet (reverse proxy) -> protected resource.
  • Policy-only degraded mode: Keep a small degraded policy set that allows low-risk baseline routes when enforcement dependencies are impaired.
  • Risk-tiered enforcement: Keep fail-closed behavior for sensitive write/admin paths; allow degraded behavior only for approved low-risk routes.

Sidecar and reverse proxy in production

  • Sidecar: Strong isolation and low latency, but traffic can fail if requests are pinned to a single sidecar listener and that listener is unavailable.
  • Reverse proxy fleet: Better for high availability because the load balancer can route around failed bouncer instances.

Enterprise checklist

  • Deploy bouncers with N+1 replicas and health checks.
  • Use pod anti-affinity / topology spread and disruption budgets.
  • Alert on heartbeat lag, policy sync lag, and bouncer readiness failures.
  • Keep failure behavior documented and approved by security + SRE teams.

🚀 Step 6: Deploy Production Bouncer

Repeat steps 1-5 for the production environment:

  1. Download bouncer package for Production environment
  2. Update configuration with production-specific settings:
    • Different bouncer_id (e.g., "bouncer-prod-api-1")
    • environment: "production"
    • Production resource URLs
  3. Deploy to production infrastructure
  4. Verify connection in Admin UI
  5. Update production DNS/routing

Important: Test policies thoroughly in Sandbox before promoting to Production!

🛡️ Policy promotion prerequisites (Sandbox -> Production)

Before promoting a policy to production, verify all of the following:

  • Production bouncer exists for the same logical resource (RESOURCE_NAME matches sandbox pair).
  • Production bouncer uses ENVIRONMENT=production and its own unique BOUNCER_ID.
  • Production resource is registered and linked to the production bouncer in Control Plane.
  • Metadata parity is confirmed across sandbox and production for policy inputs:
    • input.user attributes
    • input.resource attributes
    • input.context attributes
    • PIP-mapped attributes used by policy conditions
  • Metadata value enums are aligned between environments (for example region, risk_level, consent_status, kyc_status, identity_provider).
  • If values differ across environments, normalize values in mappings or update policy conditions before promotion.
  • Production PIP endpoints, credentials, and freshness are validated (do not assume sandbox values).
  • Production bouncer is healthy and policy sync is successful before and after promotion.

GitHub policy lifecycle expectation

  • Sandbox activate/deactivate operations should move policy artifacts between status folders.
  • Sandbox -> production promotion should copy the policy artifact into production status folders (sandbox artifact remains for continued sandbox validation/history).

🛠️ Troubleshooting

Bouncer Not Connecting

Problem: Bouncer shows as "Disconnected" in Admin UI

Solutions:

  1. Check network connectivity:

    curl -I https://your-control-plane.company.com/health

  2. Verify API credentials:

    # Check API key is valid
curl https://your-control-plane.company.com/api/v1/health \
  -H "Authorization: Bearer your-api-key-here"

  3. Check firewall rules allow outbound HTTPS (443)

  4. Review bouncer logs for errors:

    docker logs control-core-bouncer-sandbox
# or
kubectl logs deployment/control-core-bouncer-sandbox

Heartbeat Failures

Problem: Bouncer connects but heartbeat fails

Solutions:

  1. Check Control Plane health endpoint is accessible
  2. Verify heartbeat interval isn't too aggressive (min 30s recommended)
  3. Check for network instability or timeouts
  4. Review Control Plane logs for errors

Resource Not Auto-Discovered

Problem: Bouncer connects but resource doesn't appear

Solutions:

  1. Verify resource configuration in config.yaml or environment variables
  2. Ensure RESOURCE_NAME and RESOURCE_TYPE are set by your deployment
  3. Review bouncer logs for registration errors
  4. Use Confirm Connection in Settings > Bouncers (when BOUNCER_HEALTH_URL is set) to refresh status; otherwise wait for next heartbeat
  5. Manually refresh the resources page

403 Forbidden on All Requests

Problem: All requests return 403 even with valid tokens

Solutions:

  1. Check that policies are created and enabled
  2. Verify policies are assigned to the correct environment
  3. Check policy evaluation logs in Admin UI
  4. Temporarily set security_posture: "allow-all" for testing (NOT for production!)

Policy sync not updating

Problem: Bouncer is connected but policy changes are not reflected.

Solutions:

  1. Policy sync runs on an interval (default 30 seconds). Wait for the next sync or trigger a manual sync from Settings > Bouncers (open the bouncer and use Sync policies).
  2. Verify Control Plane URL and API key are set in the bouncer deployment; without them, the bouncer cannot receive policy updates.
  3. Check bouncer logs for policy sync or Policy Bridge connection errors.
  4. Ensure policies are enabled and assigned to the correct resource and environment.

High Latency

Problem: Requests through bouncer are slow

Solutions:

  1. Enable and tune cache settings:

    cache:
  enabled: true
  ttl: 300
  max_size: 5000

  2. Increase timeout values:

    network:
  timeout_seconds: 30

  3. Check Control Plane performance and scaling

  4. Deploy bouncer closer to your application (reduce network hops)

  5. Monitor bouncer resource usage (CPU/memory)

📌 Advanced Configuration

TLS/SSL Configuration

ssl:
  enabled: true
  cert_path: "/etc/certs/tls.crt"
  key_path: "/etc/certs/tls.key"
  auto_renew: true
  certificate_type: "letsencrypt"

Load Balancing (Multiple Bouncers)

Deploy multiple bouncer instances behind a load balancer for high availability:

# bouncer-1
bouncer:
  id: "bouncer-sandbox-api-1"
  name: "Sandbox API Bouncer 1"

# bouncer-2
bouncer:
  id: "bouncer-sandbox-api-2"
  name: "Sandbox API Bouncer 2"

Custom Headers

headers:
  request:
    - name: "X-Control-Core-Enforced"
      value: "true"
  response:
    - name: "X-Protected-By"
      value: "Control Core"

Traffic Routing Rules

routing:
  rules:
    - path: "/api/v1/*"
      target: "http://api-v1:8000"
    - path: "/api/v2/*"
      target: "http://api-v2:9000"

👁️ Monitoring and Observability

Metrics Endpoints

The bouncer exposes Prometheus-compatible metrics:

http://localhost:8080/metrics

Key metrics:

  • bouncer_requests_total - Total requests processed
  • bouncer_request_duration_seconds - Request latency
  • bouncer_policy_decisions_total - Policy evaluation outcomes
  • bouncer_control_plane_latency_seconds - Control Plane response time

Health Check Endpoint

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "bouncer_id": "bouncer-sandbox-api-1",
  "environment": "sandbox",
  "connected": true,
  "intercepting_traffic": true,
  "last_heartbeat": "2025-01-24T10:30:00Z",
  "control_plane_url": "https://your-control-plane.company.com",
  "uptime_seconds": 3600
}

🚀 Production Deployment Checklist

Before going to production, ensure:

  • Required env vars set by deployment: PAP_API_URL, API_KEY, BOUNCER_ID. Optionally RESOURCE_NAME, TARGET_HOST, TARGET_PORT, BOUNCER_NAME, ENVIRONMENT for correct resource registration.
  • Control Plane reachable: Bouncer can reach the Control Plane over HTTPS for registration, heartbeat, and policy sync.
  • API key valid: Use a dedicated bouncer API key with minimal required permissions; rotate periodically.
  • Pairing: For each logical resource, deploy sandbox and production bouncers with the same RESOURCE_NAME and respective ENVIRONMENT=sandbox / ENVIRONMENT=production.
  • Optional BOUNCER_HEALTH_URL: If the Control Plane can reach a bouncer health endpoint (e.g. http://<bouncer>:9901/ready), set it so Confirm Connection in the UI verifies connectivity without waiting for heartbeat.
  • Policy loading: Policies are managed from the Control Plane; no startup or manual load scripts required.
  • Verify in UI: After deploy, check Settings > Bouncers for connected status; use Confirm Connection when health URL is set.
  • No-bypass env validation: Frontend/client API URLs and server-side API URLs point to the bouncer entrypoint, not direct upstream app ports.
  • Network enforcement: Direct upstream app port is private and blocked from client-facing networks.
  • Synthetic bypass test: Automated deployment check confirms bouncer path works and direct app path is not reachable.

📌 Runtime Reliability Gate (Mandatory)

Before calling a deployment "ready", run a PBAC runtime gate that validates:

  1. Control Plane policy integrity for required controls (status + Rego markers + minimum code length).
  2. Bouncer-routed runtime behavior (role-based masking and access expectations).
  3. Medical/financial critical scenarios through the bouncer endpoint (not direct upstream).
  4. Sync remediation path (/peps/sync-all) with retry before hard failure.

Example gate commands for demo/validation environments:

bash scripts/verify-pbac-continuity.sh
python3 scripts/pbac_runtime_guard.py --auto-sync --max-retries 3 --wait-seconds 20

Fail deployment when this gate fails. Do not proceed with demos or production rollouts on partial policy health.

📌 Best Practices

Security

  • ✅ Use deny-all as default security posture
  • ✅ Rotate API keys regularly
  • ✅ Use TLS/SSL for all connections
  • ✅ Run bouncers with minimal privileges
  • ✅ Keep bouncers updated to latest version

Deployment

  • ✅ Deploy sandbox and production bouncers separately
  • ✅ Test policies in sandbox before promoting to production
  • ✅ Deploy multiple bouncer instances for high availability
  • ✅ Monitor bouncer health and performance
  • ✅ Use infrastructure as code (Helm/Terraform)

Operations

  • ✅ Enable audit logging
  • ✅ Set up alerting for bouncer disconnections
  • ✅ Monitor request latency and error rates
  • ✅ Review policy evaluation logs regularly
  • ✅ Keep configuration in version control

📌 Next Steps

  1. Create Policies: Define authorization policies in the Admin UI
  2. Test in Sandbox: Verify policies work as expected with sandbox bouncer
  3. Promote to Production: Apply tested policies to production environment
  4. Monitor: Set up dashboards and alerts for bouncer health
  5. Scale: Deploy additional bouncers as your traffic grows

📞 Support

Need help? Contact us: