From agent-almanac
Deploys and configures Kong or Traefik API gateway for traffic management, authentication, rate limiting, and routing. Use when unifying multiple backend services.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-almanac:configure-api-gatewayThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Deploy and configure an API gateway for centralized API traffic management and policy enforcement.
Deploy and configure an API gateway for centralized API traffic management and policy enforcement.
See Extended Examples for complete configuration files and templates.
Deploy the API gateway with database (Kong) or file-based config (Traefik).
For Kong with PostgreSQL:
# kong-deployment.yaml (excerpt - see EXAMPLES.md for complete file)
apiVersion: v1
kind: Namespace
metadata:
name: kong
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: kong
namespace: kong
spec:
replicas: 2
# ... (PostgreSQL, migrations, services - see EXAMPLES.md)
For Traefik:
# traefik-deployment.yaml (excerpt - see EXAMPLES.md for complete file)
apiVersion: v1
kind: Namespace
metadata:
name: traefik
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: traefik
namespace: traefik
spec:
replicas: 2
# ... (RBAC, ConfigMap, services - see EXAMPLES.md)
See EXAMPLES.md for the complete deployment manifests
Deploy:
kubectl apply -f kong-deployment.yaml # OR traefik-deployment.yaml
kubectl wait --for=condition=ready pod -l app=kong -n kong --timeout=300s
kubectl get svc -n kong kong-proxy # Get load balancer IP
Expected: Gateway pods running with 2 replicas. Load balancer service has external IP assigned. Admin API accessible (Kong: port 8001, Traefik: dashboard port 8080). Health checks passing.
On failure:
kubectl logs -n kong -l app=kongkubectl logs -n kong kong-migrations-<hash>kubectl get clusterrolebinding traefik -o yamlkubectl get svc --all-namespaces | grep 8000Define upstream services and create routes to expose APIs.
For Kong (using decK for declarative config):
# Install decK CLI
curl -sL https://github.com/Kong/deck/releases/download/v1.28.0/deck_1.28.0_linux_amd64.tar.gz | tar -xz
sudo mv deck /usr/local/bin/
# Create kong.yaml with services, routes, upstreams
# (see EXAMPLES.md for complete configuration)
deck sync --kong-addr http://localhost:8001 -s kong.yaml
curl -i http://localhost:8001/routes # Verify routes
For Traefik (using IngressRoute CRD):
# traefik-routes.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: user-api-route
spec:
entryPoints: [websecure]
routes:
- match: Host(`api.example.com`) && PathPrefix(`/api/users`)
# ... (see EXAMPLES.md for full configuration)
Apply routes:
kubectl apply -f traefik-routes.yaml
curl -H "Host: api.example.com" https://GATEWAY_IP/api/users
See EXAMPLES.md for complete routing configurations
Expected: Routes correctly proxy traffic to backend services. Weighted routing distributes traffic according to configuration. Health checks monitor backend service health.
On failure:
kubectl get svc -n defaultkubectl run test --rm -it --image=busybox -- nslookup user-service.default.svc.cluster.localkubectl logs -n kong -l app=kong --tail=50deck validate -s kong.yamlConfigure authentication plugins/middleware for API security.
For Kong (API Key and JWT authentication):
# kong-auth-config.yaml (excerpt)
consumers:
- username: mobile-app
custom_id: app-001
keyauth_credentials:
- consumer: mobile-app
key: mobile-secret-key-123
plugins:
- name: key-auth
service: user-api
# ... (see EXAMPLES.md for full configuration)
deck sync --kong-addr http://localhost:8001 -s kong-auth-config.yaml
curl -i -H "apikey: mobile-secret-key-123" http://GATEWAY_IP/api/users
For Traefik (BasicAuth and ForwardAuth middleware):
# traefik-auth-middleware.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: basic-auth-middleware
spec:
basicAuth:
secret: basic-auth
removeHeader: true
# ... (see EXAMPLES.md for OAuth2, rate limiting)
kubectl apply -f traefik-auth-middleware.yaml
curl -u user1:password https://GATEWAY_IP/api/protected
See EXAMPLES.md for complete authentication configurations
Expected: Unauthenticated requests return 401. Valid credentials allow access. Rate limiting returns 429 after threshold. JWT tokens validate correctly. ACL enforces group permissions.
On failure:
curl http://localhost:8001/consumerscurl http://localhost:8001/plugins | jq .curl -v to see response headersAdd middleware to transform requests and responses.
For Kong:
# kong-transformations.yaml (excerpt)
plugins:
- name: request-transformer
service: user-api
config:
add:
headers: [X-Gateway-Version:1.0, X-Request-ID:$(uuid)]
remove:
headers: [X-Internal-Token]
- name: correlation-id
# ... (see EXAMPLES.md for full configuration)
deck sync --kong-addr http://localhost:8001 -s kong-transformations.yaml
For Traefik:
# traefik-transformations.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: add-headers
spec:
headers:
customRequestHeaders:
X-Gateway-Version: "1.0"
# ... (see EXAMPLES.md for circuit breaker, retry, chain)
kubectl apply -f traefik-transformations.yaml
curl -v https://GATEWAY_IP/api/users | grep X-Gateway
See EXAMPLES.md for complete transformation configurations
Expected: Request headers added/removed as configured. Response headers include gateway metadata. Large requests rejected with 413. Circuit breaker trips on repeated failures. Retries occur for transient errors.
On failure:
Configure metrics, logging, and dashboards for API visibility.
Kong monitoring setup:
# kong-monitoring.yaml (excerpt)
plugins:
- name: prometheus
config:
per_consumer: true
- name: http-log
service: user-api
# ... (see EXAMPLES.md for Datadog, file-log configuration)
deck sync --kong-addr http://localhost:8001 -s kong-monitoring.yaml
# Deploy ServiceMonitor (see EXAMPLES.md)
kubectl apply -f kong-servicemonitor.yaml
curl http://localhost:8100/metrics
Traefik monitoring (built-in):
# ServiceMonitor (excerpt - see EXAMPLES.md for Grafana dashboard)
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: traefik-metrics
spec:
endpoints:
- port: metrics
path: /metrics
interval: 30s
kubectl port-forward -n traefik svc/traefik-dashboard 8080:8080
# Open http://localhost:8080/dashboard/
See EXAMPLES.md for complete monitoring configurations
Expected: Prometheus scraping gateway metrics successfully. Dashboards show request rates, latency percentiles, error rates. Logs forwarding to aggregation system. Metrics segmented by service, route, and consumer.
On failure:
kubectl get servicemonitor -Akubectl port-forward -n kong svc/kong-metrics 8100:8100Configure version management and graceful API deprecation.
Kong versioning strategy:
# kong-versioning.yaml (excerpt)
services:
- name: user-api-v1
url: http://user-service-v1.default.svc.cluster.local:8080
routes:
- name: user-v1-route
paths: [/api/v1/users]
plugins:
- name: response-transformer
config:
add:
headers:
- X-Deprecation-Notice:"API v1 deprecated on 2024-12-31"
- Sunset:"Wed, 31 Dec 2024 23:59:59 GMT"
# ... (see EXAMPLES.md for v2, default routing, rate limits)
Traefik versioning:
# traefik-versioning.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: v1-deprecation-headers
spec:
headers:
customResponseHeaders:
X-Deprecation-Notice: "API v1 deprecated on 2024-12-31"
# ... (see EXAMPLES.md for complete IngressRoutes)
Test versioning:
curl -i https://api.example.com/api/v1/users # Deprecated
curl -i https://api.example.com/api/v2/users # Current
curl -i https://api.example.com/api/users # Routes to v2
See EXAMPLES.md for complete versioning configurations
Expected: Different versions route to appropriate backend services. Deprecation headers present on v1 responses. Rate limits stricter for deprecated versions. Default path routes to latest version. Metrics segmented by API version.
On failure:
Database Dependency (Kong): Kong with database requires PostgreSQL/Cassandra. DB-less mode available but limits some features (runtime config changes). Use DB mode for production with multiple gateway instances.
Path Matching Order: Routes/IngressRoutes evaluated in specific order. More specific paths should have higher priority. Overlapping paths cause unpredictable routing. Test with curl -v to verify actual route hit.
Authentication Bypass: Ensure authentication plugins applied to all routes. Easy to add route without auth. Use default plugins at service level, then override per-route as needed.
Rate Limit Scope: Rate limiting policy: local counts per gateway pod. For consistent limits across replicas, use centralized policy (Redis) or sticky sessions.
CORS Configuration: API gateway should handle CORS, not individual services. Add CORS plugin/middleware early to avoid browser preflight failures.
SSL/TLS Termination: Gateway typically terminates SSL. Ensure certificates valid and auto-renewal configured. Use cert-manager for Kubernetes certificate management.
Upstream Health Checks: Configure active health checks to detect backend failures quickly. Passive checks rely on real traffic and may be slower to detect issues.
Plugin/Middleware Execution Order: Order matters. Authentication before rate limiting (avoid wasted rate limit slots for invalid requests). Transformation before logging (log transformed values).
Resource Limits: Gateway pods can consume significant CPU under load. Set appropriate resource requests/limits. Monitor CPU throttling in production.
Migration Strategy: Don't enable all plugins at once. Roll out incrementally: routing → authentication → rate limiting → transformations → advanced features.
configure-ingress-networking - Ingress controller setup complements API gatewaysetup-service-mesh - Service mesh provides complementary east-west traffic managementmanage-kubernetes-secrets - Certificate and credential management for gatewaysetup-prometheus-monitoring - Monitoring integration for gateway metricsenforce-policy-as-code - Policy enforcement that complements gateway authorizationnpx claudepluginhub pjt222/agent-almanacConfigures API gateways like Kong, Nginx, AWS API Gateway, and Traefik for routing, authentication, rate limiting, and request transformation in microservices.
Builds API gateways with routing, load balancing, rate limiting, authentication, circuit breakers, and health checks for multiple backend microservices.
Implements API gateway security controls including authentication enforcement, rate limiting, request validation, IP allowlisting, TLS termination, and threat protection using Kong, AWS API Gateway, Azure APIM, or Apigee.