avashya-tech-llp/claude-apps-gateway-on-eks

Purpose and Entry Points

This repository provisions a private Claude Apps Gateway on AWS EKS. Claude Code and Claude Desktop authenticate through an enterprise OIDC provider and send inference traffic to the organization’s HTTPS gateway rather than Anthropic directly.

Primary deployment entry point: Terraform/main.tf. Container image build/publish entry point: docker/claude-gateway/build-and-push.sh. Client routing is managed by scripts/switch-claude-code-to-gateway.sh and scripts/setup-claude-desktop.sh.

Infrastructure Composition

Terraform is organized as a root composition layer plus reusable AWS modules:

• Root providers, state/backend, inputs, and outputs: Terraform/providers.tf, Terraform/backend.tf, Terraform/main.tf.

• Network foundation: VPC, subnets, NAT, and private-service endpoints in Terraform/modules/networking/networking.tf and Terraform/modules/networking/vpc_endpoints.tf.

• Kubernetes control plane and managed capacity: Terraform/modules/eks/eks.tf.

• Cluster integrations, notably AWS Load Balancer Controller and EBS CSI: Terraform/modules/eks-addons/addons.tf.

• Optional DNS automation: Terraform/modules/route53/route53.tf.

Gateway Workload Boundary

The central deployment module is Terraform/modules/claude-gateway/main.tf. It declares the claude-system Kubernetes workload stack: gateway pod, ingress/ALB exposure, service identity, persistence-backed services, and optional observability components.

The gateway is built as a custom image wrapping Anthropic’s Claude Code package: docker/claude-gateway/Dockerfile. The build script publishes it to Amazon ECR, which is the runtime image source.

Request and Identity Flow

Client applications are configured to call the gateway hostname over TLS. An internet-facing AWS ALB terminates HTTPS using a supplied ACM certificate and forwards traffic into EKS.

Within the pod, nginx accepts traffic on port 8080 and forwards to the gateway on 8081. Optional ttl-proxy on 8082 removes unsupported cache_control.ttl fields for Claude 3.x APAC Bedrock models. The gateway uses external OIDC for per-user authentication and authorization; client scripts establish this gateway/OIDC configuration.

AWS Authorization and Inference Boundary

The gateway ServiceAccount receives AWS permissions through IRSA rather than static cloud credentials. This lets the running gateway invoke AWS Bedrock while maintaining a Kubernetes-to-IAM trust boundary. Bedrock region, OIDC settings, domain allow-listing, replicas, and feature flags are module inputs defined through Terraform/modules/claude-gateway/variables.tf and root Terraform/variables.tf.

External dependencies are AWS EKS, ALB, ACM, ECR, IAM/IRSA, Bedrock, and an organization-managed OIDC provider. Route53 is optional.

State, Monitoring, and Operations

Postgres stores gateway state; Loki and Grafana provide optional in-cluster observability. When monitoring is enabled, an OTel sidecar exposes telemetry and a log-forwarder forwards enhanced logs. Relevant assets include Terraform/modules/claude-gateway/log-forwarder-enhanced.py, Terraform/modules/claude-gateway/grafana-dashboard.json, and Terraform/modules/claude-gateway/grafana-dashboard-otel.json.

Operational procedures and architectural rationale are concentrated in docs/RUNBOOK.md, docs/ARCHITECTURE.md, and docs/LOGGING.md. Backup/restore scripts preserve local Claude client configuration: scripts/backup-claude-config.sh and scripts/restore-claude-config.sh.