Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Nesta página, descrevemos como usar a CLI gcloud para se conectar à sua
estação de trabalho de uma máquina local usando SSH (ou qualquer outro protocolo TCP).
O Cloud Workstations usa um túnel para encaminhar o tráfego TCP entre uma porta na sua máquina local e uma porta na estação de trabalho sem expor abertamente a estação de trabalho à Internet. As conexões são autenticadas usando
credenciais da CLI gcloud e autorizadas de acordo com as
políticas do IAM da estação de trabalho de destino.
Depois que o túnel TCP for estabelecido entre a porta local e a estação de trabalho, use-o para encaminhar o tráfego de um cliente SSH, curl ou qualquer outro aplicativo que use TCP.
Para sua conveniência, o Cloud Workstations fornece o comando
gcloud workstations ssh, que estabelece o túnel TCP e executa um cliente SSH com um
único comando da CLI gcloud.
Para todos os outros casos de uso, use o comando
gcloud workstations start-tcp-tunnel
para estabelecer o túnel TCP e execute o aplicativo que vai usar o
túnel (por exemplo, curl) em um terminal separado.
Antes de começar
Se você ainda não tiver uma estação de trabalho para se conectar,
configure uma.
Instale a CLI do Google Cloud.
Após a instalação,
inicialize a Google Cloud CLI executando o seguinte comando:
Para estabelecer uma conexão SSH segura com a estação de trabalho, use o comando
gcloud workstations ssh, que inicia um túnel TCP e executa um cliente SSH.
Para copiar o comando para o buffer de copiar e colar, clique em
content_copyCopiar exemplo de código e cole o comando em uma janela de terminal local:
PROJECT_ID: o ID do projeto Google Cloud que contém a estação de trabalho. Se omitido, o projeto atual será usado.
REGION: a região em que o cluster da estação de trabalho está
localizado. Por exemplo, us-central1.
CLUSTER_NAME: o nome do cluster de estação de trabalho
que contém a estação de trabalho.
CONFIG_NAME: o nome da configuração da estação de trabalho
que contém essas estações.
WORKSTATION_PORT (opcional): a porta na estação de trabalho
para onde o tráfego deve ser enviado. Se omitido, o tráfego será enviado para a porta
22. Todas as imagens pré-configuradas do Cloud Workstations incluem um servidor SSH que é executado
na porta 22 da estação de trabalho.
LOCAL_PORT (opcional): a porta do localhost de onde
o tráfego será enviado. Os números de porta válidos são de 1024 a 65535. Se você omitir a flag --local-host-port ou especificar uma porta de 0, uma porta não utilizada será selecionada automaticamente.
WORKSTATION_NAME: o nome da estação de trabalho.
Opcional: para transmitir flags e argumentos posicionais à implementação
ssh subjacente, adicione-os ao comando após um traço duplo (--).
Use um túnel TCP para encaminhar tráfego TCP arbitrário para sua estação de trabalho
Execute o seguinte comando da CLI gcloud para criar um túnel TCP autenticado.
Para copiar o comando para o buffer de copiar e colar, clique em
content_copyCopiar exemplo de código e cole o comando em uma janela de terminal local:
PROJECT_ID: o ID do projeto Google Cloud que contém a estação de trabalho. Se omitido, o projeto atual será usado.
REGION: a região em que o cluster da estação de trabalho está
localizado. Por exemplo, us-central1.
CLUSTER_NAME: o nome do cluster de estação de trabalho
que contém a estação de trabalho.
CONFIG_NAME: o nome da configuração da estação de trabalho que contém essas estações.
LOCAL_PORT (opcional): a porta do localhost de onde
o tráfego será enviado. Os números de porta válidos são de 1024 a 65535. Se você
omitir a flag --local-host-port ou especificar uma porta de 0, uma porta
não usada será selecionada automaticamente.
WORKSTATION_NAME: o nome da estação de trabalho.
WORKSTATION_PORT: a porta da estação de trabalho para onde
o tráfego deve ser enviado.
As imagens pré-configuradas do Cloud Workstations incluem um servidor SSH que é executado na porta 22 da estação de trabalho.
O comando da CLI gcloud executa um teste de conectividade com a
estação de trabalho, abre um túnel e mostra um número de porta:
Listening on port [LOCAL_PORT].
Todo o tráfego enviado para localhost:LOCAL_PORT é encaminhado para
a estação de trabalho. A porta é acessível apenas por aplicativos em execução no seu computador local.
Deixe a CLI gcloud em execução e abra outro terminal para executar o
aplicativo que se conecta à sua estação de trabalho.
Por exemplo, se você estiver executando um servidor na estação de trabalho que atende à porta WORKSTATION_PORT e, na etapa anterior, tiver criado um túnel TCP que encaminha o tráfego entre a porta local LOCAL_PORT e a porta da estação de trabalho WORKSTATION_PORT, execute curl na máquina local para se conectar ao servidor na estação de trabalho:
curl localhost:LOCAL_PORT
Hello, world!
Quando terminar, volte ao terminal em que você iniciou o túnel TCP e interrompa a CLI gcloud pressionando Control+C.
Usar servidores SSH em portas diferentes
As imagens de contêiner personalizadas também podem usar servidores SSH em qualquer porta. Para oferecer suporte a conexões do túnel da CLI
gcloud, configure servidores SSH personalizados para permitir a
autenticação por senha e defina o usuário de destino com uma senha vazia.
O Cloud Workstations usa o
Cloud IAM
para garantir que apenas tráfego autorizado seja enviado ao servidor SSH.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-11 UTC."],[],[],null,["# SSH support\n\nThis page describes how to use the `gcloud` CLI to connect to your\nworkstation from a local machine using SSH (or any other TCP protocol).\n\nCloud Workstations uses a tunnel to forward TCP traffic between a port on your\nlocal machine and a port on your workstation without openly exposing\nyour workstation to the internet. Connections are authenticated using\ncredentials from the `gcloud` CLI and authorized according to the\ntarget workstation's IAM policies.\n\nOnce the TCP tunnel is established between your local port and the workstation,\nyou can use it to forward traffic from an SSH client, curl, or any other\napplication that uses TCP.\n\nFor convenience, Cloud Workstations provides the\n[`gcloud workstations ssh`](/sdk/gcloud/reference/workstations/ssh)\ncommand, which establishes the TCP tunnel and runs an SSH client with a\nsingle `gcloud` CLI command.\n\nFor all other use cases, use the\n[`gcloud workstations start-tcp-tunnel`](/sdk/gcloud/reference/workstations/start-tcp-tunnel)\ncommand to establish the TCP tunnel and run the application that will use the\ntunnel (for example, `curl`) in a separate terminal.\n| **Note:** All preconfigured Cloud Workstations images include an SSH server that runs on workstation port `22`.\n\nBefore you begin\n----------------\n\n1. If you don't already have a workstation to connect to,\n [set up a workstation](/workstations/docs/quickstart-set-up-workstations-console).\n\n2.\n\n\n [Install](/sdk/docs/install) the Google Cloud CLI.\n\n After installation,\n [initialize](/sdk/docs/initializing) the Google Cloud CLI by running the following command:\n\n ```bash\n gcloud init\n ```\n\n\n If you're using an external identity provider (IdP), you must first\n [sign in to the `gcloud` CLI with your federated identity](/iam/docs/workforce-log-in-gcloud).\n\n \u003cbr /\u003e\n\n3. Make sure that you have the\n [Cloud Workstations User](/workstations/docs/access-control#workstations-user)\n IAM role on the workstation you will connect to.\n\n [Go to IAM](https://console.cloud.google.com/iam-admin/iam)\n\nConnect to your workstation using SSH\n-------------------------------------\n\nTo establish a secure SSH connection to your workstation, use the\n[`gcloud workstations ssh`](/sdk/gcloud/reference/workstations/ssh)\ncommand, which starts a TCP tunnel and runs an SSH client.\n\nTo copy the command to the copy-paste buffer, click\ncontent_copy\n**Copy code sample** and then paste the command into a local terminal window: \n\n gcloud workstations ssh \\\n --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --region=\u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e \\\n --cluster=\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --config=\u003cvar translate=\"no\"\u003eCONFIG_NAME\u003c/var\u003e \\\n --port=\u003cvar translate=\"no\"\u003eWORKSTATION_PORT\u003c/var\u003e \\\n --local-host-port=localhost:\u003cvar translate=\"no\"\u003eLOCAL_PORT\u003c/var\u003e \\\n \u003cvar translate=\"no\"\u003eWORKSTATION_NAME\u003c/var\u003e\n\nReplace the following values:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the Google Cloud project ID for the\n project containing the workstation. If omitted, the current project is\n used.\n\n- \u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e: the region where the workstation's cluster is\n located---for example, `us-central1`.\n\n- \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: the name of the workstation cluster\n containing the workstation.\n\n- \u003cvar translate=\"no\"\u003eCONFIG_NAME\u003c/var\u003e: the name of the workstation configuration\n containing this workstations.\n\n- \u003cvar translate=\"no\"\u003eWORKSTATION_PORT\u003c/var\u003e (Optional): the port on the workstation\n to which traffic should be sent. If omitted, traffic will be sent to port\n `22`. All preconfigured Cloud Workstations images include an SSH server that runs\n on workstation port `22`.\n\n- \u003cvar translate=\"no\"\u003eLOCAL_PORT\u003c/var\u003e (Optional): the localhost port from which\n traffic will be sent. Valid port numbers are `1024` to `65535`. If you omit\n the `--local-host-port` flag or specify a port of `0` an unused port is\n selected automatically.\n\n- \u003cvar translate=\"no\"\u003eWORKSTATION_NAME\u003c/var\u003e: the name of the workstation.\n\nOptional: To pass flags and positionals to the underlying `ssh`\nimplementation, append them to the command after a double-dash (`--`).\n\nUse a TCP tunnel to forward arbitrary TCP traffic to your workstation\n---------------------------------------------------------------------\n\nTo connect to a workstation using a TCP application other than `ssh`, use the\n[`gcloud workstations start-tcp-tunnel`](https://cloud.google.com/sdk/gcloud/reference/workstations/start-tcp-tunnel)\ncommand:\n\n1. Run the following `gcloud` CLI command to create an authenticated\n TCP tunnel.\n\n To copy the command to the copy-paste buffer, click\n content_copy\n **Copy code sample** and then paste the command into a local terminal window: \n\n gcloud workstations start-tcp-tunnel \\\n --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --region=\u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e \\\n --cluster=\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --config=\u003cvar translate=\"no\"\u003eCONFIG_NAME\u003c/var\u003e \\\n --local-host-port=localhost:\u003cvar translate=\"no\"\u003eLOCAL_PORT\u003c/var\u003e \\\n \u003cvar translate=\"no\"\u003eWORKSTATION_NAME\u003c/var\u003e \\\n \u003cvar translate=\"no\"\u003eWORKSTATION_PORT\u003c/var\u003e\n\n Replace the following values:\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the Google Cloud project ID for the\n project containing the workstation. If omitted, the current project is\n used.\n\n - \u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e: the region where the workstation's cluster is\n located---for example, `us-central1`.\n\n - \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: the name of the workstation cluster\n containing the workstation.\n\n - \u003cvar translate=\"no\"\u003eCONFIG_NAME\u003c/var\u003e: the name of the workstation\n configuration containing this workstations.\n\n - \u003cvar translate=\"no\"\u003eLOCAL_PORT\u003c/var\u003e (Optional): the localhost port from which\n traffic will be sent. Valid port numbers are `1024` to `65535`. If you\n omit the `--local-host-port` flag or specify a port of `0` an unused\n port is selected automatically.\n\n - \u003cvar translate=\"no\"\u003eWORKSTATION_NAME\u003c/var\u003e: the name of the workstation.\n\n - \u003cvar translate=\"no\"\u003eWORKSTATION_PORT\u003c/var\u003e: the workstation port to which\n traffic should be sent.\n [Preconfigured Cloud Workstations images](/workstations/docs/preconfigured-base-images)\n include an SSH server that runs on workstation port `22`.\n\n2. The `gcloud` CLI command performs a connectivity test with the\n workstation, opens a tunnel, and then displays a port number:\n\n Listening on port [\u003cvar translate=\"no\"\u003eLOCAL_PORT\u003c/var\u003e].\n\n All traffic sent to `localhost:`\u003cvar translate=\"no\"\u003eLOCAL_PORT\u003c/var\u003e is forwarded to\n the workstation. The port is only accessible by applications running on your\n local computer.\n3. Leave the `gcloud` CLI running and open another terminal to run the\n application that connects to your workstation.\n\n For example, if you are running a server on your workstation that serves\n port \u003cvar translate=\"no\"\u003eWORKSTATION_PORT\u003c/var\u003e, and in the previous step you\n created a TCP tunnel that forwards traffic between your local port\n \u003cvar translate=\"no\"\u003eLOCAL_PORT\u003c/var\u003e and the workstation port\n \u003cvar translate=\"no\"\u003eWORKSTATION_PORT\u003c/var\u003e, you could run `curl` on your local\n machine to connect to the server on your workstation: \n\n curl localhost:\u003cvar translate=\"no\"\u003eLOCAL_PORT\u003c/var\u003e\n Hello, world!\n\n4. When you are finished, return to the terminal where you started the TCP\n tunnel and interrupt the `gcloud` CLI by pressing\n \u003ckbd\u003eControl+C\u003c/kbd\u003e.\n\nUse SSH servers on different ports\n----------------------------------\n\n[Custom container images](/workstations/docs/custom-container-images)\ncan also use SSH servers on any port. To support connections from the\n`gcloud` CLI tunnel, you must configure custom SSH servers to allow\npassword authentication and set the target user with an empty password.\nCloud Workstations uses\n[Cloud IAM](/iam/docs/overview)\nto help ensure that only authorized traffic is sent to the SSH server.\n\nWhat's next\n-----------\n\n- [Set container environment variables in SSH sessions](/workstations/docs/customize-container-images#container_image_that_sets_container_environment_variables_in_ssh_sessions) for custom container images\n- [Enable X11 forwarding](/workstations/docs/customize-container-images#container_image_that_enables_x11_forwarding_for_ssh_sessions) for custom container images"]]