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.
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 port22
. All preconfigured Cloud Workstations images include an SSH server that runs on workstation port22
.LOCAL_PORT
(Optional): the localhost port from which traffic will be sent. Valid port numbers are1024
to65535
. If you omit the--local-host-port
flag or specify a port of0
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 are1024
to65535
. If you omit the--local-host-port
flag or specify a port of0
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 port22
.
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