zuplo 7.0.2 → 7.1.0

package/docs/articles/tunnel-troubleshooting.mdx

@@ -1,53 +1,156 @@
 ---
-title: Tunnel Troubleshooting
+title: Troubleshoot a Tunnel
+sidebar_label: Troubleshooting
 ---
 
-Setting up a secure tunnel involves configuring several different networks to
-work together. When setting up your tunnel it's common for traffic to initially
-not reach your destination initially. This is almost always caused by
-configurations (firewalls, VPCs, IAM rules, etc.) in your internal network.
+A tunnel spans your network and Zuplo's, so traffic often fails to reach its
+destination on the first attempt. The cause is usually a configuration in your
+own network — a firewall, VPC route, security group, or IAM rule — rather than
+the tunnel itself.
 
-As a quick sanity check, verify that the tunnel is running on a
-[supported Linux host](./secure-tunnel.mdx) before investigating further.
+Work through the checks on this page in order. Each one narrows down which part
+of the path is failing.
 
-## Tunnel status
+## Confirm the tunnel is connected
 
-As a first step, check if the tunnel is up and running. You can use the
-following CLI command to check the status of the tunnel:
+Start here. If the tunnel isn't connected, nothing else matters.
 
 ```bash
-# For brevity, the commands assume that you have exported your API key as an environment variable,
+# The commands below assume you exported your API key:
 # export ZUPLO_API_KEY=zpka_d67b7e241bb948758f415b79aa8exxxx_2efbxxxx
 
-zuplo tunnel list # Get the list of tunnels
-zuplo tunnel describe --tunnel-id tnl_xxxxxxxxxxx # Narrow it down to the problematic tunnel
+zuplo tunnel list
+zuplo tunnel describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx
 ```
 
-Check the `status` field from the output of `zuplo tunnel describe`. If it's
-"down" that means that your tunnel isn't up. If you are using a Docker
-container, check the container for errors. It takes a few seconds for new
-tunnels to register with the Cloudflare network for the first time.
+Check the `status` field in the output of `zuplo tunnel describe`.
 
-## Tunnel Logging
+If the status is down:
 
-If the tunnel is up (as verified in the previous step) but you aren't seeing any
-traffic, you can inspect the logs to see if there are any network or IAM issues
-that might be blocking a connection.
+- Wait a few seconds. A newly created tunnel takes a moment to register the
+  first time it connects.
+- Check the container or process for errors. A container that exits immediately
+  usually indicates a bad or missing `TUNNEL_TOKEN`.
+- Confirm the token matches the tunnel. Re-run `zuplo tunnel describe` and
+  compare it against the value your container receives. If the token was
+  rotated, the old value no longer establishes new connections.
+- Verify the host has outbound internet access. The tunnel connects outbound on
+  TCP port 7844, and the `zuplo/tunnel` image uses HTTP/2 rather than QUIC, so
+  outbound UDP isn't required. An egress firewall or proxy that blocks that port
+  prevents the tunnel from connecting.
+- Confirm the host runs Linux. See
+  [tunnel requirements](./secure-tunnel.mdx#requirements).
 
-The tunnel by default logs only errors. For the purposes of debugging, it's
-useful to set a more verbose log level. To set logging to a different level,
-simply set the environment variable `TUNNEL_LOGLEVEL` on your Zuplo tunnel
-instance to `debug`. Other log levels available are `info`, `warn`, `error`, and
-`fatal`, but `debug` is recommended for troubleshooting.
+## Check the service configuration
 
-The way you set an environment variable will vary depending on where you
-deployed the tunnel. If you are using a Docker container, you can set it as the
-environment variables for the container. See your cloud provider's documentation
-for more details.
+A connected tunnel that returns errors is often missing a service, or has one
+that's scoped to a different environment.
 
-```txt
+```bash
+zuplo tunnel services describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx
+```
+
+Compare the output against the `service://` URL your gateway calls:
+
+- **The service name matches exactly.** `service://payments-api` requires a
+  service named `payments-api`. Names are case-sensitive and don't allow partial
+  matches.
+- **Your project is listed.** A project absent from a service's `configurations`
+  can't reach it.
+- **Your environment is allowed.** Check that `accessibleBy` includes the
+  environment you're testing from: `production`, `preview`, or `working-copy`. A
+  service scoped to `production` returns an error when called from a preview
+  build.
+- **The configuration is the one you meant to upload.** Each
+  `zuplo tunnel services update` replaces the whole configuration, so a partial
+  file removes services you left out.
+
+For the meaning of each property, see
+[Service configuration reference](./tunnel-services.mdx#service-configuration-reference).
+
+## Enable debug logging
+
+If the tunnel is connected and the services look right but traffic still doesn't
+arrive, raise the log level to see what the tunnel does with each request.
+
+Set `TUNNEL_LOGLEVEL` to `debug` on your tunnel instance:
+
+```text
 TUNNEL_LOGLEVEL=debug
 ```
 
-Once you are done debugging, we recommend resetting the log level to something
-less verbose since the `debug` level can generate a lot of logs.
+How you set the variable depends on where you deployed. For a container, set it
+as a container environment variable and restart the instance. Consult your
+platform's documentation for the specific mechanism.
+
+Debug logs show each connection attempt the tunnel makes to your internal
+endpoint, which distinguishes the two common failures:
+
+- **No attempt logged.** The request isn't reaching the tunnel. Recheck the
+  service configuration and the `service://` URL in your gateway.
+- **An attempt that fails.** The tunnel is working and can't reach your backend.
+  Continue to
+  [Check connectivity to your backend](#check-connectivity-to-your-backend).
+
+Return the log level to `info` or `error` when you finish. Debug logging is
+verbose.
+
+## Check connectivity to your backend
+
+The tunnel reaches your backend the same way any other process in the same
+network position would, so reproduce the request from there.
+
+The tunnel image is distroless and has no shell, so you can't exec into it. Run
+a debug container in the same network instead:
+
+```bash
+docker run --rm --network container:zuplo-tunnel curlimages/curl \
+  -sv http://payments.internal:8080/health
+```
+
+On Kubernetes, run the equivalent pod in the same namespace as the tunnel:
+
+```bash
+kubectl run tunnel-debug --rm -it --image=curlimages/curl --restart=Never \
+  -- -sv http://payments.internal:8080/health
+```
+
+Use the exact `endpoint` value from your service configuration. Common failures:
+
+- **DNS doesn't resolve.** The tunnel host can't see your internal DNS zone. On
+  Kubernetes, confirm the service name and namespace. On ECS, check that service
+  discovery is configured for the tunnel's task.
+- **The connection times out.** A security group, network ACL, or firewall rule
+  blocks traffic from the tunnel to the backend. The tunnel's host needs egress
+  to your backend's port.
+- **The connection is refused.** The backend isn't listening on that host and
+  port, or it binds only to localhost. A backend bound to `127.0.0.1` isn't
+  reachable from a separate container or host.
+- **TLS fails.** If the endpoint uses `https` with an internal certificate
+  authority, the tunnel must trust that certificate authority. Use `http` for
+  internal traffic that's already isolated, or
+  [contact support](mailto:support@zuplo.com) to discuss certificate options.
+
+## Check the gateway side
+
+If the tunnel reaches your backend directly but requests through the gateway
+still fail, the problem is in your Zuplo project rather than the tunnel:
+
+- Confirm the route's rewrite URL or `fetch` call uses the `service://` scheme,
+  not an internal hostname. Your gateway can't resolve internal DNS names
+  directly.
+- If the URL comes from an environment variable, confirm the variable is set in
+  the environment you're testing and holds the full `service://` prefix.
+- Check your [gateway logs](./monitoring-your-gateway.mdx) for the actual error
+  status and message.
+
+## Get help
+
+If you've worked through these checks and traffic still doesn't arrive, contact
+[Zuplo support](mailto:support@zuplo.com). Include:
+
+- Your tunnel ID.
+- The output of `zuplo tunnel describe` and `zuplo tunnel services describe`.
+- Tunnel logs at `debug` level covering a failed request.
+- The `service://` URL your gateway calls and the environment you called it
+  from.

package/docs/articles/upstream-iam-auth.mdx

@@ -0,0 +1,100 @@
+---
+title: IAM Authentication for Your Backend
+sidebar_label: Overview
+---
+
+IAM authentication lets your cloud provider decide whether a request from Zuplo
+is allowed to reach your backend. Instead of sharing a secret you both store,
+your gateway proves its identity to AWS, Azure, or Google Cloud, and your
+provider's own authorization rules do the rest.
+
+Zuplo handles this with a set of upstream auth policies. Each one resolves a
+credential before your request leaves the gateway, then attaches it — as an
+`Authorization` header, or as a signature the handler computes.
+
+This approach suits backends that already run behind cloud IAM: Cloud Run, API
+Gateway, Lambda, App Service, Identity-Aware Proxy, or anything fronted by an
+identity provider you control. For the alternatives, see
+[Securing your backend](./securing-your-backend.mdx).
+
+## Federated identity or stored credentials
+
+Every provider offers two paths, and the choice matters more than which cloud
+you're on.
+
+**Federated identity** is the stronger option. Zuplo presents a short-lived,
+audience-bound OIDC token that proves which gateway is calling, and your cloud
+exchanges it for temporary credentials. No long-lived key exists, so there's
+nothing to leak or rotate. Use it when your provider supports it.
+
+**Stored credentials** mean you create a key or client secret in your cloud and
+save it as a Zuplo environment variable. This works everywhere and is simpler to
+set up, but the credential is long-lived, so you own rotating it.
+
+## Choose a policy
+
+| Provider     | Federated identity                                                                 | Stored credentials                                                                       |
+| ------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| AWS          | [Upstream AWS Federated Auth](../policies/upstream-aws-federated-auth-inbound.mdx) | [Upstream AWS Service Auth](../policies/upstream-aws-service-auth-inbound.mdx)           |
+| Google Cloud | [Upstream GCP Federated Auth](../policies/upstream-gcp-federated-auth-inbound.mdx) | [Upstream GCP Service Auth](../policies/upstream-gcp-service-auth-inbound.mdx)           |
+| Azure        | —                                                                                  | [Upstream Azure AD Service Auth](../policies/upstream-azure-ad-service-auth-inbound.mdx) |
+
+Two more policies cover cases that aren't tied to one cloud:
+
+- [Upstream GCP JWT](../policies/upstream-gcp-jwt-inbound.mdx) issues a signed
+  JWT from a service account, for backends that verify a Google-issued token
+  rather than calling an IAM-protected endpoint.
+- [Upstream OAuth Client Credentials](../policies/upstream-oauth-client-credentials-inbound.mdx)
+  handles any backend that accepts an OAuth 2.0 client credentials token,
+  including identity providers outside the three major clouds.
+
+Each policy page documents its options and the setup required on the cloud side.
+
+## How AWS differs
+
+The AWS policies behave differently from the others, and it's worth knowing
+before you configure a route. They don't add an `Authorization` header. AWS
+Signature Version 4 signs the exact final request — method, host, path, query,
+and a hash of the body — which isn't known until the handler builds it.
+
+So the AWS policies resolve credentials onto the request context, and the
+[AWS Lambda handler](../handlers/aws-lambda.mdx) or your own code signs with
+them. In custom code, read them with `AwsClient.fromContext(context)`. When you
+use the Lambda handler, attach the policy to the route and omit the handler's
+own `accessKeyId` and `secretAccessKey`.
+
+The Azure and GCP policies fetch a token and set the `Authorization` header
+themselves, so a URL Rewrite route needs no extra code.
+
+## Keep credentials out of source control
+
+Whichever policy you pick, reference secrets through environment variables
+rather than writing them into `policies.json`:
+
+```json title="config/policies.json"
+{
+  "name": "upstream-auth",
+  "policyType": "upstream-azure-ad-service-auth-inbound",
+  "handler": {
+    "export": "UpstreamAzureAdServiceAuthInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "activeDirectoryTenantId": "$env(AZURE_TENANT_ID)",
+      "activeDirectoryClientId": "$env(AZURE_CLIENT_ID)",
+      "activeDirectoryClientSecret": "$env(AZURE_CLIENT_SECRET)"
+    }
+  }
+}
+```
+
+Mark each value as a secret when you create it. For per-environment values, see
+[Configuring environment variables](./environment-variables.mdx).
+
+## Next steps
+
+- [Secure a GCP backend with Zuplo upstream auth](./gke-with-upstream-auth-policy.mdx)
+  — a full walkthrough, including Identity-Aware Proxy.
+- [Gateway to origin mTLS authentication](./securing-backend-mtls.mdx) — use
+  client certificates instead, when your backend isn't behind cloud IAM.
+- [Secure tunnel](./secure-tunnel.mdx) — reach a backend that has no public
+  endpoint at all.

package/docs/cli/tunnel-create.mdx

@@ -48,6 +48,8 @@ The following global options are available for all commands:
 
 ## Additional resources
 
-- [Secure Tunnels](../articles/secure-tunnel.mdx)
-- [Tunnel Setup & Configuration](../articles/tunnel-setup.mdx)
-- [Tunnel Troubleshooting](../articles/tunnel-troubleshooting.mdx)
+- [Secure Tunnel](../articles/secure-tunnel.mdx)
+- [Set up a Tunnel](../articles/tunnel-setup.mdx)
+- [Connect to Tunnel Services](../articles/tunnel-services.mdx)
+- [Advanced Tunnel Configuration](../articles/tunnel-advanced.mdx)
+- [Troubleshoot a Tunnel](../articles/tunnel-troubleshooting.mdx)

package/docs/cli/tunnel-create.partial.mdx

@@ -1,9 +1,13 @@
 ---
 additional-resources:
-  - name: Secure Tunnels
+  - name: Secure Tunnel
     href: ../articles/secure-tunnel.mdx
-  - name: Tunnel Setup & Configuration
+  - name: Set up a Tunnel
     href: ../articles/tunnel-setup.mdx
-  - name: Tunnel Troubleshooting
+  - name: Connect to Tunnel Services
+    href: ../articles/tunnel-services.mdx
+  - name: Advanced Tunnel Configuration
+    href: ../articles/tunnel-advanced.mdx
+  - name: Troubleshoot a Tunnel
     href: ../articles/tunnel-troubleshooting.mdx
 ---

package/docs/cli/tunnel-delete.mdx

@@ -30,6 +30,8 @@ The following global options are available for all commands:
 
 ## Additional resources
 
-- [Secure Tunnels](../articles/secure-tunnel.mdx)
-- [Tunnel Setup & Configuration](../articles/tunnel-setup.mdx)
-- [Tunnel Troubleshooting](../articles/tunnel-troubleshooting.mdx)
+- [Secure Tunnel](../articles/secure-tunnel.mdx)
+- [Set up a Tunnel](../articles/tunnel-setup.mdx)
+- [Connect to Tunnel Services](../articles/tunnel-services.mdx)
+- [Advanced Tunnel Configuration](../articles/tunnel-advanced.mdx)
+- [Troubleshoot a Tunnel](../articles/tunnel-troubleshooting.mdx)

package/docs/cli/tunnel-delete.partial.mdx

@@ -1,9 +1,13 @@
 ---
 additional-resources:
-  - name: Secure Tunnels
+  - name: Secure Tunnel
     href: ../articles/secure-tunnel.mdx
-  - name: Tunnel Setup & Configuration
+  - name: Set up a Tunnel
     href: ../articles/tunnel-setup.mdx
-  - name: Tunnel Troubleshooting
+  - name: Connect to Tunnel Services
+    href: ../articles/tunnel-services.mdx
+  - name: Advanced Tunnel Configuration
+    href: ../articles/tunnel-advanced.mdx
+  - name: Troubleshoot a Tunnel
     href: ../articles/tunnel-troubleshooting.mdx
 ---

package/docs/cli/tunnel-describe.mdx

@@ -29,12 +29,6 @@ sidebar_label: tunnel describe
   usage="$0 tunnel describe --tunnel-id <id> [options]"
 >
 
-**Additional Resources**
-
-- [Secure Tunnels](../articles/secure-tunnel.mdx)
-- [Tunnel Setup & Configuration](../articles/tunnel-setup.mdx)
-- [Tunnel Troubleshooting](../articles/tunnel-troubleshooting.mdx)
-
 </CliCommand>
 
 ## Global options
@@ -43,3 +37,11 @@ The following global options are available for all commands:
 
 - [`--help`](./global-options.mdx#help)
 - [`--api-key`](./global-options.mdx#api-key)
+
+## Additional resources
+
+- [Secure Tunnel](../articles/secure-tunnel.mdx)
+- [Set up a Tunnel](../articles/tunnel-setup.mdx)
+- [Connect to Tunnel Services](../articles/tunnel-services.mdx)
+- [Advanced Tunnel Configuration](../articles/tunnel-advanced.mdx)
+- [Troubleshoot a Tunnel](../articles/tunnel-troubleshooting.mdx)

package/docs/cli/tunnel-describe.partial.mdx

@@ -1,5 +1,13 @@
-**Additional Resources**
-
-- [Secure Tunnels](../articles/secure-tunnel.mdx)
-- [Tunnel Setup & Configuration](../articles/tunnel-setup.mdx)
-- [Tunnel Troubleshooting](../articles/tunnel-troubleshooting.mdx)
+---
+additional-resources:
+  - name: Secure Tunnel
+    href: ../articles/secure-tunnel.mdx
+  - name: Set up a Tunnel
+    href: ../articles/tunnel-setup.mdx
+  - name: Connect to Tunnel Services
+    href: ../articles/tunnel-services.mdx
+  - name: Advanced Tunnel Configuration
+    href: ../articles/tunnel-advanced.mdx
+  - name: Troubleshoot a Tunnel
+    href: ../articles/tunnel-troubleshooting.mdx
+---

package/docs/cli/tunnel-list.mdx

@@ -30,6 +30,8 @@ The following global options are available for all commands:
 
 ## Additional resources
 
-- [Secure Tunnels](../articles/secure-tunnel.mdx)
-- [Tunnel Setup & Configuration](../articles/tunnel-setup.mdx)
-- [Tunnel Troubleshooting](../articles/tunnel-troubleshooting.mdx)
+- [Secure Tunnel](../articles/secure-tunnel.mdx)
+- [Set up a Tunnel](../articles/tunnel-setup.mdx)
+- [Connect to Tunnel Services](../articles/tunnel-services.mdx)
+- [Advanced Tunnel Configuration](../articles/tunnel-advanced.mdx)
+- [Troubleshoot a Tunnel](../articles/tunnel-troubleshooting.mdx)

package/docs/cli/tunnel-list.partial.mdx

@@ -1,9 +1,13 @@
 ---
 additional-resources:
-  - name: Secure Tunnels
+  - name: Secure Tunnel
     href: ../articles/secure-tunnel.mdx
-  - name: Tunnel Setup & Configuration
+  - name: Set up a Tunnel
     href: ../articles/tunnel-setup.mdx
-  - name: Tunnel Troubleshooting
+  - name: Connect to Tunnel Services
+    href: ../articles/tunnel-services.mdx
+  - name: Advanced Tunnel Configuration
+    href: ../articles/tunnel-advanced.mdx
+  - name: Troubleshoot a Tunnel
     href: ../articles/tunnel-troubleshooting.mdx
 ---

package/docs/cli/tunnel-rotate-token.mdx

@@ -37,3 +37,11 @@ The following global options are available for all commands:
 
 - [`--help`](./global-options.mdx#help)
 - [`--api-key`](./global-options.mdx#api-key)
+
+## Additional resources
+
+- [Secure Tunnel](../articles/secure-tunnel.mdx)
+- [Set up a Tunnel](../articles/tunnel-setup.mdx)
+- [Connect to Tunnel Services](../articles/tunnel-services.mdx)
+- [Advanced Tunnel Configuration](../articles/tunnel-advanced.mdx)
+- [Troubleshoot a Tunnel](../articles/tunnel-troubleshooting.mdx)

package/docs/cli/tunnel-rotate-token.partial.mdx

@@ -0,0 +1,13 @@
+---
+additional-resources:
+  - name: Secure Tunnel
+    href: ../articles/secure-tunnel.mdx
+  - name: Set up a Tunnel
+    href: ../articles/tunnel-setup.mdx
+  - name: Connect to Tunnel Services
+    href: ../articles/tunnel-services.mdx
+  - name: Advanced Tunnel Configuration
+    href: ../articles/tunnel-advanced.mdx
+  - name: Troubleshoot a Tunnel
+    href: ../articles/tunnel-troubleshooting.mdx
+---

package/docs/cli/tunnel-services-describe.mdx

@@ -40,6 +40,8 @@ The following global options are available for all commands:
 
 ## Additional resources
 
-- [Secure Tunnels](../articles/secure-tunnel.mdx)
-- [Tunnel Setup & Configuration](../articles/tunnel-setup.mdx)
-- [Tunnel Troubleshooting](../articles/tunnel-troubleshooting.mdx)
+- [Secure Tunnel](../articles/secure-tunnel.mdx)
+- [Set up a Tunnel](../articles/tunnel-setup.mdx)
+- [Connect to Tunnel Services](../articles/tunnel-services.mdx)
+- [Advanced Tunnel Configuration](../articles/tunnel-advanced.mdx)
+- [Troubleshoot a Tunnel](../articles/tunnel-troubleshooting.mdx)

package/docs/cli/tunnel-services-describe.partial.mdx

@@ -1,9 +1,13 @@
 ---
 additional-resources:
-  - name: Secure Tunnels
+  - name: Secure Tunnel
     href: ../articles/secure-tunnel.mdx
-  - name: Tunnel Setup & Configuration
+  - name: Set up a Tunnel
     href: ../articles/tunnel-setup.mdx
-  - name: Tunnel Troubleshooting
+  - name: Connect to Tunnel Services
+    href: ../articles/tunnel-services.mdx
+  - name: Advanced Tunnel Configuration
+    href: ../articles/tunnel-advanced.mdx
+  - name: Troubleshoot a Tunnel
     href: ../articles/tunnel-troubleshooting.mdx
 ---

package/docs/cli/tunnel-services-update.mdx

@@ -46,3 +46,11 @@ The following global options are available for all commands:
 
 - [`--help`](./global-options.mdx#help)
 - [`--api-key`](./global-options.mdx#api-key)
+
+## Additional resources
+
+- [Secure Tunnel](../articles/secure-tunnel.mdx)
+- [Set up a Tunnel](../articles/tunnel-setup.mdx)
+- [Connect to Tunnel Services](../articles/tunnel-services.mdx)
+- [Advanced Tunnel Configuration](../articles/tunnel-advanced.mdx)
+- [Troubleshoot a Tunnel](../articles/tunnel-troubleshooting.mdx)

package/docs/cli/tunnel-services-update.partial.mdx

@@ -0,0 +1,13 @@
+---
+additional-resources:
+  - name: Secure Tunnel
+    href: ../articles/secure-tunnel.mdx
+  - name: Set up a Tunnel
+    href: ../articles/tunnel-setup.mdx
+  - name: Connect to Tunnel Services
+    href: ../articles/tunnel-services.mdx
+  - name: Advanced Tunnel Configuration
+    href: ../articles/tunnel-advanced.mdx
+  - name: Troubleshoot a Tunnel
+    href: ../articles/tunnel-troubleshooting.mdx
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.0.2",
+  "version": "7.1.0",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.0.2",
-    "@zuplo/core": "7.0.2",
-    "@zuplo/runtime": "7.0.2",
-    "@zuplo/test": "7.0.2"
+    "@zuplo/cli": "7.1.0",
+    "@zuplo/core": "7.1.0",
+    "@zuplo/runtime": "7.1.0",
+    "@zuplo/test": "7.1.0"
   }
 }

package/docs/cli/tunnel-rate-token.partial.mdx

@@ -1,9 +0,0 @@
----
-additional-resources:
-  - name: Secure Tunnels
-    href: ../articles/secure-tunnel.mdx
-  - name: Tunnel Setup & Configuration
-    href: ../articles/tunnel-setup.mdx
-  - name: Tunnel Troubleshooting
-    href: ../articles/tunnel-troubleshooting.mdx
----