Update tunnel docs

docs/articles/secure-tunnel.md

@@ -25,7 +25,7 @@ build in virtually any format (i.e. an Azure VM, etc.). The tunnel itself is a
 lightweight service that when started makes an outbound connection to the Zuplo
 network and then through to your Zuplo Gateway.
 
-When the tunnel service connects to the Zuplo network traffic from your gateway
+When the tunnel service connects to the Zuplo network, traffic from your gateway
 can be routed to internal services running in your network or VPC. For example,
 if your API is running on the internal DNS address `external-api.local`, the
 tunnel will route traffic from the Zuplo API Gateway to your internal service
@@ -77,10 +77,8 @@ solution that meets your scale requirements.
 You should run your tunnel with an IAM role or other network policies that only
 allow the tunnel to make requests to the network services that you want your
 Gateway to access. This can be done in a variety of ways depending on your
-setup. IAM roles and internal service meshes are common means of controlling
-which services the tunnel can access. For example, at Zuplo we use
-[Linkerd](https://linkerd.io/) in our Kubernetes clusters as one mechanism for
-controlling what services are accessible to our tunnel deployment.
+setup. IAM roles, network segregation, and internal service meshes are common
+means of controlling which services the tunnel can access.
 
 For details on how to configure a tunnel on your network see
 [the setup guide](tunnel-setup.md).

docs/articles/tunnel-setup.md

@@ -82,9 +82,9 @@ one for staging.
 
 ## Using Services Exposed through Tunnels in Config
 
-Services can also be used in config 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.
+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.
 
 ![](https://cdn.zuplo.com/assets/0c91be91-a591-4cef-ac29-d266e8a3181e.png)
 

docs/articles/tunnel-troubleshooting.md

@@ -7,17 +7,44 @@ work together. When setting up your tunnel it is 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.
 
+## Tunnel status
+
+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:
+
+```bash
+# For brevity, the commands assume that you have exported your API key as an environment variable,
+# export ZUPLO_API_KEY=zpka_d67b7e241bb948758f415b79aa8exxxx_2efbxxxx
+
+zup tunnel list # Get the list of tunnels
+zup tunnel describe --tunnel-id tnl_xxxxxxxxxxx # Narrow it down to the problematic tunnel
+```
+
+Check the `status` field from the output of `zup tunnel describe`. If it is
+"down" that means that your tunnel is not 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.
+
 ## Tunnel Logging
 
+If the tunnel is up (as verified in the previous step) but you are not seeing
+any traffic, you can inspect the logs to see if there are any network or IAM
+issues that might be blocking a connection.
+
 The tunnel by default logs only errors. For the purposes of debugging, it is
 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.
 
 The way you set an environment variable will vary depending on where you
-deployed the tunnel. See your cloud provider's documentation for more details.
+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.
 
 ```txt
 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.

docs/cli/tunnels.md

@@ -3,7 +3,7 @@ title: Tunnel Commands
 ---
 
 ```bash
-[I] ➜ zup tunnel --help
+zup tunnel --help
 zup tunnel
 
 Tunnel commands