SSH support

This page describes how to use the gcloud CLI to connect to your workstation from a local machine using SSH (or any other TCP protocol).

Cloud Workstations uses a tunnel to forward TCP traffic between a port on your local machine and a port on your workstation without openly exposing your workstation to the internet. Connections are authenticated using credentials from the gcloud CLI and authorized according to the target workstation's IAM policies.

Once the TCP tunnel is established between your local port and the workstation, you can use it to forward traffic from an SSH client, curl, or any other application that uses TCP.

For convenience, Cloud Workstations provides the gcloud workstations ssh command, which establishes the TCP tunnel and runs an SSH client with a single gcloud CLI command.

For all other use cases, use the gcloud workstations start-tcp-tunnel command to establish the TCP tunnel and run the application that will use the tunnel (for example, curl) in a separate terminal.

Before you begin

If you don't already have a workstation to connect to, set up a workstation.
Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
Make sure that you have the Cloud Workstations User IAM role on the workstation you will connect to.

Go to IAM

Connect to your workstation using SSH

To establish a secure SSH connection to your workstation, use the gcloud workstations ssh command, which starts a TCP tunnel and runs an SSH client.

To copy the command to the copy-paste buffer, click Copy code sample and then paste the command into a local terminal window:

gcloud workstations ssh \
    --project=PROJECT_ID \
    --region=REGION \
    --cluster=CLUSTER_NAME \
    --config=CONFIG_NAME  \
    --port=WORKSTATION_PORT  \
    --local-host-port=localhost:LOCAL_PORT  \
    WORKSTATION_NAME

Replace the following values:

PROJECT_ID: the Google Cloud project ID for the project containing the workstation. If omitted, the current project is used.
REGION: the region where the workstation's cluster is located—for example, us-central1.
CLUSTER_NAME: the name of the workstation cluster containing the workstation.
CONFIG_NAME: the name of the workstation configuration containing this workstations.
WORKSTATION_PORT (Optional): the port on the workstation to which traffic should be sent. If omitted, traffic will be sent to port 22. All preconfigured Cloud Workstations images include an SSH server that runs on workstation port 22.
LOCAL_PORT (Optional): the localhost port from which traffic will be sent. Valid port numbers are 1024 to 65535. If you omit the --local-host-port flag or specify a port of 0 an unused port is selected automatically.
WORKSTATION_NAME: the name of the workstation.

Optional: To pass flags and positionals to the underlying ssh implementation, append them to the command after a double-dash (--).

Use a TCP tunnel to forward arbitrary TCP traffic to your workstation

To connect to a workstation using a TCP application other than ssh, use the gcloud workstations start-tcp-tunnel command:

Run the following gcloud CLI command to create an authenticated TCP tunnel.

To copy the command to the copy-paste buffer, click Copy code sample and then paste the command into a local terminal window:
```
gcloud workstations start-tcp-tunnel \
    --project=PROJECT_ID \
    --region=REGION \
    --cluster=CLUSTER_NAME \
    --config=CONFIG_NAME \
    --local-host-port=localhost:LOCAL_PORT \
    WORKSTATION_NAME \
    WORKSTATION_PORT
```
Replace the following values:
- PROJECT_ID: the Google Cloud project ID for the project containing the workstation. If omitted, the current project is used.
- REGION: the region where the workstation's cluster is located—for example, us-central1.
- CLUSTER_NAME: the name of the workstation cluster containing the workstation.
- CONFIG_NAME: the name of the workstation configuration containing this workstations.
- LOCAL_PORT (Optional): the localhost port from which traffic will be sent. Valid port numbers are 1024 to 65535. If you omit the --local-host-port flag or specify a port of 0 an unused port is selected automatically.
- WORKSTATION_NAME: the name of the workstation.
- WORKSTATION_PORT: the workstation port to which traffic should be sent. Preconfigured Cloud Workstations images include an SSH server that runs on workstation port 22.
The gcloud CLI command performs a connectivity test with the workstation, opens a tunnel, and then displays a port number:
```
Listening on port [LOCAL_PORT].
```
All traffic sent to localhost:LOCAL_PORT is forwarded to the workstation. The port is only accessible by applications running on your local computer.
Leave the gcloud CLI running and open another terminal to run the application that connects to your workstation.

For example, if you are running a server on your workstation that serves port WORKSTATION_PORT, and in the previous step you created a TCP tunnel that forwards traffic between your local port LOCAL_PORT and the workstation port WORKSTATION_PORT, you could run curl on your local machine to connect to the server on your workstation:
```
curl localhost:LOCAL_PORT
Hello, world!
```
When you are finished, return to the terminal where you started the TCP tunnel and interrupt the gcloud CLI by pressing Control+C.

Use SSH servers on different ports

Custom container images can also use SSH servers on any port. To support connections from the gcloud CLI tunnel, you must configure custom SSH servers to allow password authentication and set the target user with an empty password. Cloud Workstations uses Cloud IAM to help ensure that only authorized traffic is sent to the SSH server.

What's next

Set container environment variables in SSH sessions for custom container images
Enable X11 forwarding for custom container images