zuplo 7.0.2 → 7.1.1

package/docs/articles/tunnel-services.mdx

@@ -0,0 +1,165 @@
+---
+title: Connect to Tunnel Services
+sidebar_label: Connect to Services
+---
+
+<EnterpriseFeature name="Secure tunneling" />
+
+Once a tunnel exposes a service, your gateway calls it like any other backend —
+with a URL. Tunnel services use the `service://` scheme instead of a hostname,
+so a service named `payments-api` is reachable at `service://payments-api`.
+
+This page covers the service configuration file, and the three places you use a
+`service://` URL: handler code, route configuration, and environment variables.
+To create a tunnel first, see [Set up a tunnel](./tunnel-setup.mdx).
+
+## Service configuration reference
+
+You define services in a JSON file and upload it with
+[`zuplo tunnel services update`](../cli/tunnel-services-update.mdx). Each upload
+replaces the tunnel's entire configuration.
+
+```json title="tunnel-config.json"
+{
+  "version": 1,
+  "services": [
+    {
+      "name": "payments-api-prod",
+      "endpoint": "http://payments.internal:8080",
+      "configurations": [
+        {
+          "project": "my-project",
+          "accessibleBy": ["production"]
+        },
+        {
+          "project": "my-other-project",
+          "accessibleBy": ["production"]
+        }
+      ]
+    },
+    {
+      "name": "payments-api-staging",
+      "endpoint": "http://payments-staging.internal:8080",
+      "configurations": [
+        {
+          "project": "my-project",
+          "accessibleBy": ["preview", "working-copy"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Property                        | Type     | Description                                                                                                             |
+| ------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `version`                       | number   | Configuration format version. Use `1`.                                                                                  |
+| `services`                      | array    | The services this tunnel exposes.                                                                                       |
+| `services[].name`               | string   | The service name your gateway calls, used as `service://<name>`.                                                        |
+| `services[].endpoint`           | string   | The internal URL the tunnel forwards to, resolvable from the tunnel host. For example, `http://payments.internal:8080`. |
+| `services[].configurations`     | array    | Which projects and environments can call this service. A project that isn't listed can't reach the service.             |
+| `configurations[].project`      | string   | The name of the Zuplo project.                                                                                          |
+| `configurations[].accessibleBy` | string[] | The environments allowed to call the service. Valid values are `production`, `preview`, and `working-copy`.             |
+
+Use `accessibleBy` to keep environments apart. A service listed only under
+`production` can't be reached from a preview build, even by a developer on your
+own team.
+
+To see the configuration a tunnel currently has, run
+[`zuplo tunnel services describe`](../cli/tunnel-services-describe.mdx).
+
+## Call a service from code
+
+Pass the `service://` URL to `fetch` exactly as you would a public URL:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const response = await fetch("service://payments-api-prod/v1/charges");
+
+  if (!response.ok) {
+    context.log.error(`Payments API returned ${response.status}`);
+    return new Response("Upstream error", { status: 502 });
+  }
+
+  return response;
+}
+```
+
+Paths, query strings, headers, and request methods all work the way they do for
+a normal `fetch`. The tunnel appends the path to the service's configured
+`endpoint`.
+
+## Call a service from route configuration
+
+Any route property that accepts a URL accepts a `service://` URL, including the
+[URL Rewrite handler](../handlers/url-rewrite.mdx):
+
+```json title="config/routes.oas.json"
+{
+  "paths": {
+    "/v1/charges": {
+      "get": {
+        "x-zuplo-route": {
+          "handler": {
+            "export": "urlRewriteHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "rewritePattern": "service://payments-api-prod/v1/charges"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+You can also set the rewrite URL in the **Rewrite URL** field of the route
+editor in the Zuplo Portal.
+
+## Switch services per environment
+
+Most teams run a separate internal service for each environment. Rather than
+changing code or route configuration per environment, store the service URL in
+an [environment variable](./environment-variables.mdx) and set a different value
+in each Zuplo environment.
+
+In your production environment, point the variable at the production service:
+
+```text
+TUNNEL_BASE_URL=service://payments-api-prod
+```
+
+In preview and working-copy environments, point it at staging:
+
+```text
+TUNNEL_BASE_URL=service://payments-api-staging
+```
+
+Read the variable in handler code:
+
+```ts
+import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  return fetch(`${environment.TUNNEL_BASE_URL}/v1/charges`);
+}
+```
+
+Environment variables work in route configuration too. The following URL Rewrite
+handler combines the variable with a path parameter:
+
+<Framed>
+
+![The Request Handler pane of the Zuplo route editor, with Handler set to URL Rewrite and Rewrite URL set to a value that combines the TUNNEL_BASE_URL environment variable with a path parameter](../../public/media/tunnel-setup/16b93099-511d-435b-af85-167fab5814b2.png)
+
+</Framed>
+
+## Next steps
+
+- [Advanced tunnel configuration](./tunnel-advanced.mdx) — the cloudflared
+  foundation, environment variables, and self-managed images.
+- [Troubleshoot a tunnel](./tunnel-troubleshooting.mdx) — diagnose requests that
+  don't reach your backend.

package/docs/articles/tunnel-setup.mdx

@@ -1,227 +1,180 @@
 ---
-title: Tunnel Setup & Use
+title: Set up a Tunnel
+sidebar_label: Setup
 ---
 
 <EnterpriseFeature name="Secure tunneling" />
 
-:::caution{title="Platform Requirement"}
+This guide takes you from nothing to a working tunnel: you create the tunnel in
+Zuplo, run the tunnel container inside your network, tell Zuplo which internal
+services to expose, and confirm the connection is up.
 
-The Zuplo tunnel service is officially supported on **Linux** only. The
-[`zuplo/tunnel` Docker image](https://hub.docker.com/r/zuplo/tunnel) is a Linux
-container, and any non-containerized deployment must target a Linux host. Cloud
-container platforms (AWS ECS, Azure Container Instances, GCP Cloud Run,
-Kubernetes) run Linux containers by default and require no extra configuration.
-If you are deploying on a virtual machine or bare metal, ensure the host runs a
-supported Linux distribution.
+For background on what a tunnel does and how it fits your architecture, see
+[Secure tunnel](./secure-tunnel.mdx).
 
-:::
+## Before you begin
 
-## Setting up Tunnels
+You need:
 
-A tunnel is a way to expose your _internal services_ to the Zuplo gateway
-without exposing it to the public internet. Your Zuplo Gateway accesses those
-services through the `service://` protocol.
+- The [Zuplo CLI](../cli/overview.mdx) installed and authenticated.
+- A Linux host or container runtime inside the network that holds your backend
+  API. The host needs outbound internet access and internal DNS resolution to
+  your backend.
+- The internal endpoint of each service you want to expose, such as
+  `http://payments.internal:8080`.
 
 ## Create the tunnel
 
-Before you deploy the tunnel container, create the tunnel in Zuplo using the
-CLI. This gives you the tunnel record in your account and the token that you
-will later provide to the container as `TUNNEL_TOKEN`.
+<Stepper>
 
-```bash
-zuplo tunnel create --tunnel-name <your-tunnel-name>
-zuplo tunnel list
-zuplo tunnel describe --tunnel-id <your-tunnel-id>
-```
-
-Use these commands as follows:
-
-1. Run `zuplo tunnel create` to create the tunnel.
-1. Run `zuplo tunnel list` to see the tunnels in your account and identify the
-   tunnel ID if you need it.
-1. Run `zuplo tunnel describe` with the tunnel ID to retrieve the tunnel details
-   and copy the token value you will use for `TUNNEL_TOKEN`.
-
-The easiest way to deploy your tunnel is using a Docker container. The three
-basic requirements for deploying a secure tunnel with Docker are:
-
-1. A tunnel secret that's provided to the Docker container as an environment
-   variable named `TUNNEL_TOKEN` (the secret is provided by the Zuplo CLI when
-   you create the tunnel. See [creating a tunnel](../cli/tunnel-create.mdx))
-1. The ability for the tunnel service to make an outbound connection to the
-   public internet to establish the secure tunnel.
-1. The ability for the tunnel service to make a request to your internal API by
-   a DNS address. (for example `https://my-service.local/api`).
-
-The tunnel can run anywhere you can deploy a Docker container. Where you deploy
-depends on your specific setup. To run the Docker container on your own
-infrastructure, refer to instructions from your cloud provider or contact
-[Zuplo support](mailto:support@zuplo.com) for assistance.
-
-Below are a few option for deploying the tunnel.
-
-- [Deploying Docker containers on Azure](https://docs.microsoft.com/en-us/learn/modules/run-docker-with-azure-container-instances/)
-- [Deploying Docker containers on AWS ECS](https://docs.aws.amazon.com/AmazonECS/latest/userguide/getting-started.html)
-- [Deploying container images to GCP](https://cloud.google.com/compute/docs/containers/deploying-containers)
-
-The docker container is `zuplo/tunnel` and is available on
-[Docker Hub](https://hub.docker.com/r/zuplo/tunnel).
-
-Your running container needs a single environment variable named `TUNNEL_TOKEN`.
-You should store the value as a secret using the recommended means of secret
-storage and environment variable injection for your platform.
-
-## Configuring services
-
-Once you have created a tunnel, you can
-[configure which services](../cli/tunnel-services-update.mdx) it should expose
-using a configuration file. Below is a sample configuration file. The properties
-in the `services` objects are explained below.
-
-- `name` - This is the name of the service that you will use from your Zuplo
-  project
-- `endpoint` - This is the local endpoint of your service that you tunnel can
-  connect to
-- `configurations` - This object specifies which projects and which environments
-  can access this service.
-  - `project` - The name of the Zuplo project
-  - `accessibleBy` - The environments which can use the tunnel. Valid values are
-    `production`, `preview`, and `working-copy`.
-
-```json title="tunnel-config.json"
-{
-  "version": 1,
-  "services": [
-    {
-      "name": "my-awesome-service-prod",
-      "endpoint": "http://localhost:8000",
-      "configurations": [
-        {
-          "project": "my-project",
-          "accessibleBy": ["production"]
-        },
-        {
-          "project": "my-other-project",
-          "accessibleBy": ["production"]
-        }
-      ]
-    },
-    {
-      "name": "my-awesome-service-staging",
-      "endpoint": "http://localhost:9000",
-      "configurations": [
-        {
-          "project": "my-project",
-          "accessibleBy": ["preview", "working-copy"]
-        },
-        {
-          "project": "my-other-project",
-          "accessibleBy": ["preview", "working-copy"]
-        }
-      ]
-    }
-  ]
-}
-```
-
-```bash
-zuplo tunnel services update \
---configuration-file <path-to-your-configuration-file> \
---tunnel-id <your-tunnel-id>
-```
-
-## Using Services Exposed through Tunnels in Code
-
-Once set up, the services in the tunnels can be treated like any API host that
-you call from your Zuplo gateway. Each service exposed through tunnels is called
-with the URL schema `service://`, so if your service is named
-`my-awesome-service` you will call it using the URL
-`service://my-awesome-service`.
-
-This URL can be used in code as shown below.
-
-```ts
-import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+1. Create the tunnel in your Zuplo account:
 
-export default async function (request: ZuploRequest, context: ZuploContext) {
-  const response = await fetch("service://my-awesome-service/hello-world");
-  if (response.status > 399) {
-    return "It didn't work. :(";
-  } else {
-    return response;
-  }
-}
-```
-
-It's common to have multiple services for each of your internal environments.
-Each service can be restricted so that it's only accessible by specific Zuplo
-environments. For example, you might have two services one for production and
-one for staging.
-
-- `service://my-awesome-service-prod` (Production)
-- `service://my-awesome-service-staging` (Staging)
+   ```bash
+   zuplo tunnel create --tunnel-name my-tunnel
+   ```
 
-## Using Services Exposed through Tunnels in Configuration
+   The command returns the tunnel ID, which starts with `tnl_`. Record it — the
+   remaining commands need it. To look it up later, run `zuplo tunnel list`.
 
-Services can also be used in routes.oas.json file such as with the URL Rewrite
-handler. To call a tunnel service simply use it as part of the rewrite URL as
-shown in the image below.
+1. Retrieve the tunnel's connection token:
 
-![Zuplo route handling](../../public/media/tunnel-setup/0c91be91-a591-4cef-ac29-d266e8a3181e.png)
+   ```bash
+   zuplo tunnel describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx
+   ```
 
-## Service Environment Variables
+   Copy the token value from the output. The tunnel container authenticates with
+   this token.
 
-When using these services in your code or configuration, it's often useful to
-store the values as an environment variable. This way you can change which
-environment calls which tunnel without changing code or configuration.
+   :::caution
 
-For the production environment you would set the `BASE_SERVICE_URL` to the
-production service name. See
-[this document](../articles/environment-variables.mdx) for more about
-[Environment Variables](../articles/environment-variables.mdx)
+   The token grants the ability to connect to your tunnel. Store it in your
+   platform's secret manager rather than in source control or a plain
+   environment file. If a token is exposed, see
+   [Rotate the tunnel token](./tunnel-advanced.mdx#rotate-the-tunnel-token).
 
-```text
-BASE_SERVICE_URL=service://my-awesome-service-prod
-```
+   :::
 
-And for staging, you would use the staging service name.
+</Stepper>
 
-```text
-BASE_SERVICE_URL=service://my-awesome-service-staging
-```
+## Run the tunnel
 
-In your handler code or other configuration, the service can be accessed using
-the environment variable.
+Deploy the [`zuplo/tunnel`](https://hub.docker.com/r/zuplo/tunnel) container
+anywhere inside your network. It takes a single environment variable,
+`TUNNEL_TOKEN`, set to the token from the previous step.
 
-```ts
-import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+To confirm the token works before you wire up your deployment platform, run the
+container locally on a host inside your network:
 
-export default async function (request: ZuploRequest, context: ZuploContext) {
-  const response = await fetch(`${environment.BASE_SERVICE_URL}/hello-world`);
-  if (response.status > 399) {
-    return "It didn't work. :(";
-  } else {
-    return response;
-  }
-}
+```bash
+docker run -d --name zuplo-tunnel \
+  -e TUNNEL_TOKEN=<YOUR_TUNNEL_TOKEN> \
+  zuplo/tunnel:latest
 ```
 
-Environment variables can also be used in configuration, such as the URL Rewrite
-handler as shown below.
-
-![Zuplo environment variables](../../public/media/tunnel-setup/16b93099-511d-435b-af85-167fab5814b2.png)
-
-## Tunnel Upgrades
-
-Zuplo publishes a new release of the tunnel Docker image about once per month or
-whenever Cloudflare ships a release to their underlying tunnel tools. The most
-recent version of the Docker Image is always tagged with the `latest` tag. We
-recommend periodically checking and upgrading the tunnel to the latest release
-to ensure you have the latest security and performance updates.
-
-We recommend testing each release of the tunnel in a staging environment before
-rolling out to production.
-
-## Troubleshooting
+Replace `<YOUR_TUNNEL_TOKEN>` with the token you copied. For production, pin a
+specific image tag instead of `latest` and inject the token from your secret
+manager. For details, see
+[Advanced tunnel configuration](./tunnel-advanced.mdx).
 
-For troubleshooting see [this document](./tunnel-troubleshooting.mdx).
+Run at least two instances so the tunnel survives the loss of a single host or
+pod. Instances that share the same token act as replicas of one tunnel.
+
+Where you deploy depends on your infrastructure. The following guides cover the
+common platforms:
+
+- [Deploy containers on AWS ECS](https://docs.aws.amazon.com/AmazonECS/latest/userguide/getting-started.html)
+- [Deploy containers on Azure Container Instances](https://docs.microsoft.com/en-us/learn/modules/run-docker-with-azure-container-instances/)
+- [Deploy container images on GCP](https://cloud.google.com/compute/docs/containers/deploying-containers)
+
+For help with a platform that isn't listed, contact
+[Zuplo support](mailto:support@zuplo.com).
+
+## Expose your internal services
+
+A running tunnel doesn't expose anything by itself. You define the services it
+forwards to in a configuration file, then upload that file to Zuplo.
+
+<Stepper>
+
+1. Create a configuration file that names each service, its internal endpoint,
+   and the Zuplo projects and environments allowed to call it:
+
+   ```json title="tunnel-config.json"
+   {
+     "version": 1,
+     "services": [
+       {
+         "name": "payments-api-prod",
+         "endpoint": "http://payments.internal:8080",
+         "configurations": [
+           {
+             "project": "my-project",
+             "accessibleBy": ["production"]
+           }
+         ]
+       },
+       {
+         "name": "payments-api-staging",
+         "endpoint": "http://payments-staging.internal:8080",
+         "configurations": [
+           {
+             "project": "my-project",
+             "accessibleBy": ["preview", "working-copy"]
+           }
+         ]
+       }
+     ]
+   }
+   ```
+
+   For the meaning of each property, see
+   [Service configuration reference](./tunnel-services.mdx#service-configuration-reference).
+
+1. Upload the configuration to your tunnel:
+
+   ```bash
+   zuplo tunnel services update \
+     --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx \
+     --configuration-file ./tunnel-config.json
+   ```
+
+   The upload replaces the tunnel's entire service configuration, so include
+   every service you want available each time you run it.
+
+</Stepper>
+
+## Verify the tunnel
+
+<Stepper>
+
+1. Check that the tunnel reports itself as connected:
+
+   ```bash
+   zuplo tunnel describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx
+   ```
+
+   Look at the `status` field. A new tunnel takes a few seconds to register the
+   first time it connects. If the status stays down, see
+   [Troubleshoot a tunnel](./tunnel-troubleshooting.mdx).
+
+1. Confirm Zuplo has the services you uploaded:
+
+   ```bash
+   zuplo tunnel services describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx
+   ```
+
+1. Call a service from your gateway. Add a route to your project that rewrites
+   to one of your service URLs, such as `service://payments-api-prod`, and send
+   a request to it. For the full set of ways to call a service, see
+   [Connect to tunnel services](./tunnel-services.mdx).
+
+</Stepper>
+
+## Next steps
+
+- [Connect to tunnel services](./tunnel-services.mdx) — call `service://` URLs
+  from handler code, route configuration, and environment variables.
+- [Advanced tunnel configuration](./tunnel-advanced.mdx) — pin image versions,
+  tune the connection, rotate tokens, and build your own image.
+- [Troubleshoot a tunnel](./tunnel-troubleshooting.mdx) — work through a tunnel
+  that's down or not passing traffic.