# 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