chore: add docs for sharing ports (#13136)

Co-authored-by: kirby <kirby@coder.com>
Co-authored-by: Stephen Kirby <me@skirby.dev>

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)