cloudlysis/gateway/DEPLOYMENT.md

Deployment Notes

Swarm Ingress and TLS

Gateway exposes:

• HTTP: :8080
• gRPC: :8081

Recommended pattern in Swarm:

• Terminate TLS at an ingress proxy (Traefik / Nginx / Envoy) on the overlay network.
• Route HTTP and gRPC to the Gateway service by port.
• Prefer L7 routing (Host + Path for HTTP, SNI for gRPC) and keep the Swarm routing mesh disabled unless you explicitly want it.

Secrets

The Swarm stack expects these secrets to exist:

• gateway_jwt_secrets (comma-separated or newline-separated signing secrets)
• google_oidc_client_id
• google_oidc_client_secret

The container reads them via:

• GATEWAY_JWT_SECRETS_FILE
• GOOGLE_OIDC_CLIENT_ID_FILE
• GOOGLE_OIDC_CLIENT_SECRET_FILE

Internal mTLS (Optional)

Gateway can be configured to use mTLS when calling internal upstreams.

HTTP upstream (reqwest):

• GATEWAY_INTERNAL_CA_CERT_PEM_FILE
• GATEWAY_INTERNAL_IDENTITY_PEM_FILE (combined cert + key PEM)

gRPC upstream (tonic):

• GATEWAY_INTERNAL_GRPC_TLS = true|false (or use https:// upstream URLs)
• GATEWAY_INTERNAL_GRPC_CA_CERT_PEM_FILE
• GATEWAY_INTERNAL_GRPC_CLIENT_CERT_PEM_FILE
• GATEWAY_INTERNAL_GRPC_CLIENT_KEY_PEM_FILE

HA Validation (Manual)

With gateway running at replicas: 2:

• Verify /ready stays healthy during rolling updates.
• Verify refresh rotation works across replicas (no sticky sessions):
  • Sign in → refresh from one replica → refresh again against the other replica and confirm the old token is rejected.
• Verify admin IAM changes are visible across replicas:
  • Create a role/assignment via /admin/iam on one replica → call an authorized endpoint via the other replica.

Suggested Procedure

1. Deploy the stack:
   • docker stack deploy -c swarm/stacks/platform.yml cloudlysis
2. Confirm gateway has 2 running tasks:
   • docker service ps cloudlysis_gateway
3. Smoke readiness (at least one replica reachable through ingress):
   • curl -fsS http://localhost:8080/ready
4. Refresh across replicas:
   • Run the refresh flow twice while forcing traffic to different replicas (hostnames or per-task published ports if you use an ingress proxy).
5. Rolling update guard:
   • Update the image tag and redeploy, then watch:
     • docker service ps cloudlysis_gateway
     • curl -fsS http://localhost:8080/ready in a loop