diff --git a/docs/images/networking/annotatedports.png b/docs/images/networking/annotatedports.png new file mode 100644 index 0000000000000..3fb3c705df43a Binary files /dev/null and b/docs/images/networking/annotatedports.png differ diff --git a/docs/images/networking/listeningports.png b/docs/images/networking/listeningports.png new file mode 100644 index 0000000000000..cfc21e923368e Binary files /dev/null and b/docs/images/networking/listeningports.png differ diff --git a/docs/images/networking/portforwarddashboard.png b/docs/images/networking/portforwarddashboard.png new file mode 100644 index 0000000000000..dd71c41bd8d86 Binary files /dev/null and b/docs/images/networking/portforwarddashboard.png differ diff --git a/docs/images/networking/portsharingmax.png b/docs/images/networking/portsharingmax.png new file mode 100644 index 0000000000000..1deae4d449947 Binary files /dev/null and b/docs/images/networking/portsharingmax.png differ diff --git a/docs/networking/port-forwarding.md b/docs/networking/port-forwarding.md index 9f5ec0ddce494..09597bb94f9db 100644 --- a/docs/networking/port-forwarding.md +++ b/docs/networking/port-forwarding.md @@ -60,18 +60,9 @@ For more examples, see `coder port-forward --help`. > name, agent name, workspace name and username exceed 63 characters in the > hostname, port forwarding via the dashboard will not work. -### From an arbitrary port - -One way to port forward in the dashboard is to use the "Port forward" button to -specify an arbitrary port. Coder will also detect if apps inside the workspace -are listening on ports, and list them below the port input (this is only -supported on Windows and Linux workspace agents). - -![Port forwarding in the UI](../images/port-forward-dashboard.png) - ### From an coder_app resource -Another way to port forward is to configure a `coder_app` resource in the +One way to port forward is to configure a `coder_app` resource in the workspace's template. This approach shows a visual application icon in the dashboard. See the following `coder_app` example for a Node React app and note the `subdomain` and `share` settings: @@ -99,7 +90,68 @@ Valid `share` values include `owner` - private to the user, `authenticated` - accessible by any user authenticated to the Coder deployment, and `public` - accessible by users outside of the Coder deployment. -![Port forwarding from an app in the UI](../images/coderapp-port-forward.png) +![Port forwarding from an app in the UI](../images/networking/portforwarddashboard.png) + +## Accessing workspace ports + +Another way to port forward in the dashboard is to use the "Open Ports" button +to specify an arbitrary port. Coder will also detect if apps inside the +workspace are listening on ports, and list them below the port input (this is +only supported on Windows and Linux workspace agents). + +![Port forwarding in the UI](../images/networking/listeningports.png) + +### Sharing ports + +We allow developers to share ports as URLs, either with other authenticated +coder users or publicly. Using the open ports interface, developers can assign a +sharing levels that match our `coder_app`’s share option in +[Coder terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app#share). + +- `owner` (Default): The implicit sharing level for all listening ports, only + visible to the workspace owner +- `authenticated`: Accessible by other authenticated Coder users on the same + deployment. +- `public`: Accessible by any user with the associated URL. + +Once a port is shared at either `authenticated` or `public` levels, it will stay +pinned in the open ports UI for better accessibility regardless of whether or +not it is still accessible. + +![Annotated port controls in the UI](../images/networking/annotatedports.png) + +This can also be used to change the sharing level of `coder_app`s by entering +their port number in the shared ports UI. The `share` attribute of `coder_app`s +defined using the terraform provider can be overridden by sharing the port. The +sharing level is limited by the maximum level enforced by the template in +enterprise deployments, and not restricted in OSS deployments. + +### Configure maximum port sharing level (enterprise) + +Enterprise-licensed template admins can control the maximum port sharing level +for workspaces under a given template in the template settings. By default, the +maximum sharing level is set to `Owner`, meaning port sharing is disabled for +end-users. OSS deployments allow all workspaces to share ports at both the +`authenticated` and `public` levels. + +![Max port sharing level in the UI](../images/networking/portsharingmax.png) + +### Configuring port protocol + +Both listening and shared ports can be configured to use either `HTTP` or +`HTTPS` to connect to the port. For listening ports the protocol selector +applies to any port you input or select from the menu. Shared ports have +protocol configuration for each shared port individually. + +You can access any port on the workspace and can configure the port protocol +manually by appending a `s` to the port in the URL. + +``` +# Uses HTTP +https://33295--agent--workspace--user--apps.example.com/ +# Uses HTTPS +https://33295s--agent--workspace--user--apps.example.com/ +``` ### Cross-origin resource sharing (CORS)