add docs on 0.0.0.0 gotcha

docs/docs/advanced-concepts/public-and-private-ips-and-ports.md

@@ -42,3 +42,9 @@ grafana-1670597488       grafana       http: 3000/tcp -> 127.0.0.1:55998
 The IP address used to reach these containers is your localhost address, `127.0.0.1`. This is the "public IP address" of each container in the cluster.
 
 The combination of public IP + port _will_ allow you to connect to a container from your command line. For example, from the output above, `curl 127.0.0.1:55947` on your command line would make a request to private port `4000` on the `cl-client-0-beacon` service.
+
+### Gotchas
+
+When exposing a port on a `ServiceConfig` via the `ports` field, the container responsible for managing the enclave, APIContainer (APIC), will perform an availability check (`nc -vz <service ip> <port>`) to ensure the port is exposed.
+Some services by default expose ports on `localhost:<port num>` or `127.0.0.1:<port num>`. This would cause the availability check (eg. `nc -vz 172.0.0.3 9612`) to fail as the APIC communicates with the service on a subnetwork created by Kurtosis for that enclave,
+whilst the port is only exposed on the localhost network interface. The workaround is to expose the port on all network interfaces via `0.0.0.0` eg. `--rpc.laddr tcp://0.0.0.0:36657`.

docs/docs/api-reference/starlark-reference/service-config.md

@@ -270,6 +270,15 @@ See [`NixBuildSpec`][nix-build-spec] for more information on how to use the Nix
 
 You can view more information on [configuring the `ReadyCondition` type here][ready-condition].
 
+:::note
+If you are experiencing issues with unsuccessful port check, try exposing the port on all network interfaces via `0.0.0.0` eg `--rpc.laddr tcp://0.0.0.0:36657`). See [here][port-ip-doc] for an in depth explanation.
+```bash
+  == FINISHED SERVICE 'service-a' LOGS ===================================
+  Caused by: An error occurred while waiting for all TCP and UDP ports to be open
+  Caused by: Unsuccessful ports check for IP '172.16.0.10' and port spec '{privatePortSpec:0x400071d0b0}', even after '240' retries with '500' milliseconds in between retries. Timeout '2m0s' has been reached
+```
+:::
+
 :::tip
 If you are trying to use a more complex versions of `cmd` and are running into issues, we recommend using `cmd` in combination with `entrypoint`. You can
 set the `entrypoint` to `["/bin/sh", "-c"]` and then set the `cmd` to the command as you would type it in your shell. For example, `cmd = ["echo foo | grep foo"]`
@@ -320,3 +329,4 @@ The `tolerations` field expects a list of [`Toleration`][toleration] objects bei
 [user]: ./user.md
 [toleration]: ./toleration.md
 [nix-build-spec]: ./nix-build-spec.md
+[port-ip-doc]: ../../advanced-concepts/public-and-private-ips-and-ports.md